Troubleshooting

Start with the exact failure, selected gateway, agent, conversation, and execution target. A healthy panel, a reachable model, an online worker, and successful external delivery are separate checks.

The local gateway never becomes readyCopy Anchor Link

Use Show the log to inspect local-gateway.log, then Try again now after resolving the cause. The log records startup and the reason an early process exit occurred. Check the app version, available disk space, and the concrete error before changing data files.

Do not delete the embedded database or regenerate the local key file as a first step. Those contain your agent state and decryption material.

The web panel loads but the gateway failsCopy Anchor Link

Check /web/health and /health separately. In Compose, web talks to gateway:4310; the browser talks to the web service. An incorrect JIAN_GATEWAY_URL can leave the panel reachable while API operations fail.

Inspect make ps and make logs. Confirm that web and gateway images use matching release tags. For streaming stalls, inspect reverse-proxy buffering and idle timeouts.

Sign-in or remote connection failsCopy Anchor Link

Use the host owner token, not a channel/worker/provider token. Confirm the base URL without /v1, a query, or embedded credentials. Check TLS and the published major.minor compatibility line.

A GitHub or MCP callback returning to the wrong address points to callback/public-URL/proxy configuration. On desktop, a local port change can require reconnecting those sign-ins.

PostgreSQL reports 28P01Copy Anchor Link

PostgreSQL applies POSTGRES_PASSWORD when its volume is initialized. Replacing .env later does not change the existing database role's password.

Reconcile the configured password with the existing database account using your database administration procedure. Do not delete the volume to “make the password take effect”; that deletes the installation's data.

A provider is connected but the task failsCopy Anchor Link

Identify the activity: conversation, compaction, image analysis, image generation, audio, or speech. Check its model default and the provider's error. A subscription chat connection may not provide a separate media capability.

For compatible endpoints, test network reachability from the gateway's actual host/container. localhost in a container is not your computer. Review model configuration and private-origin policy.

A connected machine is offline or outdatedCopy Anchor Link

• Confirm the machine is awake and the user/service has started.
• Inspect jian-remote version and restart the installed worker if appropriate.
• Check outbound HTTPS access to the configured gateway address.
• Confirm the current worker token after a rotation.
• Resolve Update needed by aligning the worker's major.minor line.
• For an app-managed machine, check the desktop sharing switch and whether the app is running.

Online shell access with failing screenshots points to OS permissions or the desktop session, not necessarily the polling connection. See Computer Use troubleshooting.

The agent seems to forgetCopy Anchor Link

Check whether the fact is in the selected profile's Memories, not just in a different gateway, agent, or chat. Recall is selective and budgeted. A memory with poorly chosen wording may not match the current request; linked entries only follow one hop.

For an exact earlier statement, search conversation history. For a repeated method, inspect the skill description and whether it was loaded. Compaction preserves a summary, not every detail. Learning can conclude “Nothing to keep”; inspect its conversation before assuming a write happened.

An action waits or is refusedCopy Anchor Link

Inspect the conversation protection and the approval card. A channel contact may be allowed to chat but not to approve. A subagent may need its parent to request approval. This is different from an expired provider token.

Review the action before changing protection. Full access is not a general-purpose fix for a confusing error.

A message is accepted but no reply arrivesCopy Anchor Link

For channel ingress, HTTP 202 is receipt, not proof that a run started. Inspect accepted, contact status, run ID, AI-enabled status, and later delivery. A pending contact must be approved before normal work starts.

For OpenAI-compatible clients, a pending contact returns 403. A disconnected client does not automatically cancel a gateway run; inspect the conversation before resubmitting as a new request.

Report useful evidenceCopy Anchor Link

Include the app/gateway/worker versions, OS, selected target, exact error text, reproduction steps, and whether the failure repeats. Redact owner tokens, worker tokens, provider secrets, connection strings, and private screenshots. Share the relevant log excerpt, not an entire configuration directory.