PacketAgentDocs

Troubleshoot PacketAgent#

Work from the platform inward: process readiness, storage, authentication, deployment status, trigger delivery, provider routing, then tool execution.

Before you start#

  • Record the application version, Worker definition, version, deployment, and run identifiers.
  • Collect server and sandbox logs around the failure without copying secrets.
  • Preserve the run events and external side-effect evidence before retrying.
  • Confirm whether the problem affects one Worker or the whole installation.

Check health and storage#

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

Resolve readiness before investigating individual runs.

Common failures#

Symptom Check Recovery
Startup rejects the vault or preview configuration Production secret or origin is missing Supply a new secret and two different HTTPS origins.
Ready returns 503 Store cannot open or runtime dependency is unavailable Check database URL, file mount, migrations, and permissions.
Sign-in fails Cookie origin, account policy, or rate limit is wrong Confirm HTTPS, proxy trust, and access policy.
Registration returns 403 The instance is invite-only and already holds an account Send a fresh invitation and register with its code.
Version cannot validate Required Worker fields or Docker validation failed Complete the version and restore Docker access.
Package validate or deploy reports package.signature.required or package.signature.untrusted The credential requires a signature, and either none was supplied or no active signing key in this workspace verified the envelope Register the publisher's Ed25519 public key in the workspace, or re-sign the package with a registered key.
Deployment remains draft Version is not frozen or policy compilation failed Freeze a valid version and create a new deployment revision.
Manual run works but cron does not No active scheduler leader Configure and verify one leader.
Webhook does not create a run Credential, header, deployment, or deduplication key is wrong Rotate the webhook credential and send a new unique test event.
Run remains waiting An approval request is unresolved Approve or reject it before its deadline.
Run ends with lease_lost Another runtime holds the run's execution lease, or the store rejected renewal Confirm one runtime owns the deployment, then check store write health and host clock skew before restarting the run.
Run stops partway through with a deadline The run exhausted its elapsed budget Raise the Worker's elapsed budget or split the work into shorter runs.
Provider call fails Credential, endpoint, model, or provider quota failed Test the provider outside the Worker and select a supported model.
A run using tools fails with a provider 400 on its second model call The installation predates assistant tool-call replay Upgrade to the current release.
Run fails immediately after a model reply The provider returned a refusal, which ends the phase rather than continuing Change the Worker prompt or inputs; the same input produces the same refusal.
A workbench action returns 403 An older workbench build dropped the request token on calls that set custom headers Upgrade and reload the workbench. Import agent, worker run pause, resume and stop, revoke deployment, and attention approve and reject are affected.
Tool is denied Compiled deployment policy does not grant the effect and resource Create and activate a reviewed deployment with the narrow grant.
Notification is not delivered Route or endpoint failed through all retries Correct it and redrive the dead letter.

A rejected registration returns the same 403 whether the invitation is unknown, expired, revoked, already used, or issued to a different email address. Diagnose it from the invitation record in the workspace, not from the response.

Verify#

  1. Confirm readiness.
  2. Validate the Worker version.
  3. Activate a new deployment revision when configuration changed.
  4. Run a manual test with a unique identifier.
  5. Confirm events, usage, approvals, artifacts, and notifications reach their expected terminal states.
  6. Check that no external operation was repeated unexpectedly.