Troubleshooting

1. Logs — open the Logs tab, uncheck everything except WARN and ERROR, and scroll up to the most recent red line. That’s usually the answer.
2. Danger tab — the Danger tab is the inventory page. Check status, last sync, the lifecycle-script state, and whether your secrets show as Synced.
3. Console — the Console is a shell. tail /tmp/user-build.log, env, ps aux answer about 80% of “why doesn’t my service work” questions.
4. Files — if something used to work and broke after a recent change, restore an earlier snapshot from the Files tab.
5. Validate config — POST /v0/templates/validate checks manifest.json; POST /v0/agents/{agentId}/config/validate checks the engine runtime config shown on the Danger tab. These are different files, see Concepts for the difference.

​

Agent won’t start / stays in starting

# Are we still spinning up the container?
curl -H "Authorization: Bearer $PINATA_JWT" \
  https://agents.pinata.cloud/v0/agents/$AGENT_ID | jq '.processStatus'

# Did the build script blow up?
# Console → tail -n 200 /tmp/user-build.log

​

Gateway won’t connect / chat is offline

​

Build script failed

# Console
tail -n 200 /tmp/user-build.log

• Wrong working directory - build runs from /home/node/clawd, not the workspace
• Missing tooling (pnpm, yarn) - install in the build script first, or use a tool that ships with the image (npm)
• package.json not found - cd into the right project subfolder
• 5-minute timeout - split the work or pre-install in a snapshot

​

Start script crashes immediately

tail -n 200 /tmp/user-start.log
ss -tlnp

​

Routes not working / 404 / 502

# Is your service even listening?
ss -tlnp

# Hit it from inside the container
curl -i http://localhost:5173/

# Does the route show up in the API?
curl -H "Authorization: Bearer $PINATA_JWT" \
  https://agents.pinata.cloud/v0/agents/$AGENT_ID/port-forwarding

​

Secret update didn’t apply

​

Skill missing / not loading

# Is it actually attached?
curl -H "Authorization: Bearer $PINATA_JWT" \
  https://agents.pinata.cloud/v0/agents/$AGENT_ID | jq '.skills'

# Are the files in the workspace?
# Console: ls workspace/skills/

​

Custom domain stuck pending

# Confirm DNS
dig TXT _pinata-verify.app.example.com +short

# Re-trigger verification
curl -X POST \
  -H "Authorization: Bearer $PINATA_JWT" \
  https://agents.pinata.cloud/v0/agents/$AGENT_ID/domains/$DOMAIN_ID/verify

​

Device pairing rejects / stuck pending

curl -H "Authorization: Bearer $PINATA_JWT" \
  https://agents.pinata.cloud/v0/agents/$AGENT_ID/devices

• The device never sent an approval request - re-pair from the client
• You’re on a different workspace than the one you approved from - check Account → Workspaces
• The agent is not_running - pairing requires the gateway to be up

​

Git push rejected

​

Tasks aren’t firing

• Is the task enabled? GET /v0/agents/{agentId}/tasks with includeDisabled=true
• Is the agent running? Tasks fire only while the gateway is up; missed runs during downtime are skipped
• Check cron/runner lines in Logs around the expected time
• Trigger manually: POST /v0/agents/{agentId}/tasks/{jobId}/run - if that works, the schedule is wrong

​

Costs / model usage looks off

​

Still stuck?

• Agent ID (Danger → Agent → Agent ID)
• Engine and version, if shown on the Danger tab
• A recent EXPORT VISIBLE from the Logs tab (filter to ERROR first)
• The relevant section of manifest.json if config-related
• What you expected vs. what happened