← All articles

Step 1: Check if the agent is paused

The most common reason an agent isn't running is that it's paused.

In the dashboard: Agents → your agent → Status

If paused, check the pause reason:

• Manual pause: Someone (you) paused it. Click Resume.
• Budget exceeded: The agent hit its monthly budget. Check current month spend and either increase the budget limit or wait for the month to reset.
• Error pause: Paperclip paused the agent after too many consecutive errors. Check the Runs tab for what went wrong.

Step 2: Check recent runs

Agent → Runs tab shows every heartbeat execution with:

• Start/end time
• Duration
• Error (if any)
• Task worked on

Look for patterns:

• All runs failing with the same error? Likely a config problem.
• Runs completing but task not progressing? Check the task status and agent instructions.
• No runs at all? The heartbeat isn't triggering.

Step 3: Heartbeat not triggering

If the Runs tab shows no runs (or none recently), the heartbeat isn't firing.

Check heartbeat config:

{
  "heartbeat": {
    "enabled": true,      // Must be true
    "intervalSec": 3600,  // How often (in seconds)
    "wakeOnDemand": true  // Should wake on task assignment
  }
}

If enabled: false, the agent won't run. Set it to true.

Check server time: If your server's clock is significantly off, cron-based heartbeats may not fire as expected. Sync time:

timedatectl status
sudo timedatectl set-ntp true

Step 4: Run failing with authentication error

Error: authentication failed
Error: ANTHROPIC_API_KEY not set or invalid
Error: claude_auth_required

Fix: Check the agent's API key in the dashboard (Agent → Secrets). Verify it's set and valid:

# Test the key directly
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-haiku-4-5-20251001", "max_tokens": 10, "messages": [{"role": "user", "content": "Hi"}]}'

401 response = invalid or expired key. Create a new key at console.anthropic.com.

Step 5: Agent picks up task but doesn't make progress

If the task sits in in_progress for a long time:

1. Check if the run is still active: Runs tab — is there an active run? If yes, it may just be slow (some agent tasks take 10–30 minutes).

2. Run timeout: If timeoutSec is set low, the run might be timing out before the agent finishes. Increase it or set to 0 (no timeout).

3. maxTurnsPerRun too low: If the task requires more turns than allowed, the agent stops mid-work. Increase maxTurnsPerRun from 50 to 150+.

4. Agent is blocked waiting for input: Check the task's comments — the agent may have posted a question and marked itself blocked.

Step 6: Task never gets picked up

If a task is assigned to the agent but sits in todo without being picked up:

1. Agent status: Is the agent Running (not Paused)?
2. Task status: Is the task in todo, backlog, or blocked? Agents pick up todo and in_progress tasks. blocked is skipped unless explicitly addressed.
3. Heartbeat interval: If intervalSec: 86400 (daily), you may need to wait. Use wakeOnDemand: true for immediate pickup on task assignment.

Step 7: Agent makes too many errors

If an agent repeatedly fails and pauses itself:

1. Look at the error message in the last failing run

2. Common causes:

   • Instructions file not found: Check instructionsFilePath points to a real file
   • Working directory doesn't exist: Agent can't find its workspace
   • Out of memory: Server is OOM-killing the Claude subprocess. Upgrade RAM.

3. Fix the root cause before resuming — the agent will keep pausing if the underlying problem isn't resolved.

Step 8: Agent produces wrong output

Not a crash, but the agent isn't doing what you want:

1. Read the agent's comments: Look at what it wrote on the task
2. Check the instructions: Are they specific enough? Vague instructions produce vague output
3. Update AGENTS.md: Add clearer examples or constraints
4. Reassign the task: Let the agent try again with better instructions

Most "wrong output" issues are instruction quality issues, not agent capability issues.

Quick diagnostic commands

# Check Paperclip server is running
systemctl status paperclip

# View recent logs
journalctl -u paperclip -n 100 --no-pager

# Check for errors in logs
journalctl -u paperclip --since "1 hour ago" -p err

# Check memory (OOM kills)
journalctl --since "1 hour ago" | grep -i "oom\|killed\|out of memory"

# Check disk space
df -h

When to open a support issue

If you've checked all of the above and the agent still isn't working:

1. Collect the agent's run logs (from the Runs tab)
2. Copy the error message exactly
3. Note your Paperclip version (paperclipai --version) and Node.js version (node --version)
4. Search the Paperclip GitHub issues or community for similar reports

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.