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 after its thirty-second executor lease expires; legacy runs without a lease use twenty minutes. A recovered run reports timed_out with run_abandoned. Inspect side effects before starting another run.
Agent draft changes are ignored Runs use the published version Publish and start a new run.
Approved agent run stays queued Its continuation cannot reach an executor Restore the worker and Redis, then poll the same run before retrying an action.
Attached file is stored but not used as context Text extraction reports unsupported, empty or failed Use a readable supported text document; storage success alone does not prove model context.
Share link returns 404 It was revoked, is invalid, or its recorded conversation path is unavailable Ask the owner for a new reviewed link.

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.