Skip to main content

Troubleshooting

The App Does Not Start​

For Docker Compose, check the rendered configuration, container state, logs, and health endpoint:

docker compose --env-file values.env config --quiet
docker compose --env-file values.env ps
docker compose --env-file values.env logs --tail=200 synth

set -a
. ./values.env
set +a
curl -fsS "$SYNTH_PUBLIC_URL/health"

If the configured HTTP port is already in use, change SYNTH_HTTP_PORT and SYNTH_PUBLIC_URL in values.env, then restart:

${EDITOR:-vi} values.env
docker compose --env-file values.env down
docker compose --env-file values.env up -d

For Kubernetes, check rollout, pods, events, and logs:

kubectl -n synth rollout status deploy/synth --timeout=10m
kubectl -n synth get deploy,po,svc,ingress,pvc
kubectl -n synth describe pod -l app.kubernetes.io/instance=synth
kubectl -n synth logs deploy/synth --tail=200

Ingest Fails​

Check:

  • extract agent has a provider and model
  • source URL is public
  • Git URL is GitHub.com or GitLab.com HTTPS/SSH, or an arbitrary generic Git URL explicitly enabled with SYNTH_ALLOW_ARBITRARY_GIT_URLS=1; restart the affected service or pod after changing the setting
  • a private self-hosted GitLab or GitHub repository uses its HTTPS clone URL ending in .git with the matching GitLab or GitHub PAT credential, or its SSH clone URL with an SSH-key credential; PATs authenticate clone operations but do not enable groups, provider discovery, or provider API reconciliation
  • arbitrary Git remains an operator opt-in because cloning occurs from the Synth server's network; enable it only for trusted watcher managers and use network policy to constrain unintended destinations
  • uploaded file is under the configured size limit

If a watcher says Git is current, but knowledge sync is blocked, the remote repository check succeeded but Synth did not activate a new Project snapshot. Open the watcher logs and use the reported page path and report ID to identify the failed publication. After correcting the cause or rolling out a fixed Synth image, choose Check now. Synth retains the files as pending and retries them; it does not treat an unchanged Git commit as a successful knowledge sync.

For Helm installs, put settings needed by both URL validation and cloning in top-level extraEnv. It is applied to the web and ingestion-worker containers. Use ingestionWorker.extraEnv only for worker-specific additions.

For a Git collection that reports a catalog error, do not recreate the watcher. Check the provider credential and rate-limit status, then use Full reconcile. Synth retains the last complete catalog during incomplete or failed enumeration. If a verified provider-side change would remove many repositories, review the proposed removals and issue the one-use approval from the watcher card.

Explore Reports That The Project Is Unready​

Explore does not need a model. Check that ingestion completed and that the canonical Project snapshot/index is active. An unready Project is not reported as an authoritative empty result.

Imported Git Project Has No Graph​

Remote Git imports build graph state from Markdown files under knowledge/. Check that the remote project folder contains knowledge/concepts, knowledge/entities, or another knowledge category with .md files. Raw files outside knowledge/ are not enough; ingest or watch those sources first.

See Remote Git Backends.

Imported Git Project Has Pages But Explore Finds Nothing​

Search for an exact phrase from the imported pages. If Explore does not find the pages, check the project folder and make sure Pull existing knowledge after creation was enabled during import.

MCP Says 401​

Create a fresh key and paste it into your client:

Authorization: Bearer synth_sk_REPLACE_ME

MCP Says 406​

Add this header:

Accept: application/json, text/event-stream

The Agent Uses The Wrong Project​

Tell it the project name, or make it call synth_list_projects first.

The Brief Is Weak​

Synth is telling you the project memory is thin. Add the doc, runbook, or source that the agent should have read, then run the brief again.

Need Raw API Docs​

Open the API docs on your running Synth URL:

https://synth.example.com/api/docs