PacketChatDocs

Troubleshoot PacketChat#

Diagnose PacketChat from its dependencies inward: readiness, authentication, provider account, model binding, then the individual workspace feature.

Before you start#

  • Record the application version and deployment time.
  • Collect web and worker logs around the failure without copying credentials.
  • Confirm whether the problem affects one user, one provider, or the whole installation.
  • Keep a reversible backup before changing database or storage state.

Check readiness#

test -n "$PACKETCHAT_URL" || { echo "Set PACKETCHAT_URL to the deployed origin" >&2; exit 1; }
curl -i "$PACKETCHAT_URL/api/readyz"

The probe answers even while a dependency is down. The three checks run together and each one is bounded at three seconds, so an unresponsive dependency is reported instead of stalling the probe. A 503 body names the failing check as database, redis, or objectStorage.

Resolve any database, Redis, or object-storage failure before investigating chat or agent behaviour.

Common failures#

Symptom Check Recovery
Startup rejects configuration Required value is absent or unsafe for production Regenerate the named secret or correct the URL and cookie settings.
Login loops after success Secure cookie and proxy scheme disagree Confirm HTTPS, COOKIE_SECURE=true, public base URL, and proxy headers.
User cannot sign in Status, password, session, or reset state is invalid Issue a reset and verify the account remains active.
Invite or reset email does not arrive The response, the Users page, and the audit record report emailDelivery as failed Hand over the link shown beside the invite or reset, correct the email settings, then issue a new one. A failed send is never retried.
Provider test fails Key, base URL, or provider-side access is wrong Correct the account and test again before discovery.
Model is missing Discovery did not return an enabled binding Review discovery output and the provider model-list permission.
Chat returns no stream Provider request failed or the model binding changed Test the account, select an enabled model, and inspect web logs.
Document stays queued Worker or Redis is unavailable Restore the worker and Redis, then retry ingestion.
Document fails File processing or object storage failed Inspect worker logs and verify the object exists and fits limits.
Rate limits stop being applied Redis is unavailable, so the limiter allows the request and logs Rate limit check failed; allowing request unthrottled at error level Restore Redis. Limits resume without a restart; treat the gap as a period of unthrottled sign-in attempts when reviewing logs.
Asynchronous agent run stays queued The worker is stopped or is not consuming the agent-run queue Restore the worker. A queued run is claimed when a worker returns; waiting in the queue does not fail it.
Agent run stays running and never produces output Its executor stopped before the run finished Read the run again after 20 minutes from its start. The status read marks an abandoned run timed_out with run_abandoned, then start a new run.
Agent draft changes are ignored Runs use the published version Publish and start a new run.
Approved agent action ends the run Current approval flow does not resume generation Start a follow-up run with the action result.

Verify#

  1. Confirm readiness.
  2. Sign in through a fresh private browser session.
  3. Test the provider account.
  4. Send and reload a short conversation.
  5. Upload a small text document and wait for ready status.
  6. Start one agent run and confirm it reaches a terminal status.
  7. Confirm usage and audit records were written.