Troubleshooting

Start with the job’s log: ask Claude “show the last log of the digest”. Its summary line usually says what’s wrong.

A job is blocked

Cause: the Runner stops and marks the task blocked when something it needs is missing, most often a login: git or gh couldn’t reach GitHub, or a key the skill uses isn’t there. It never looks for credentials itself.

Fix:

1. Read the task’s summary: it names the error, and usually says “connect it on CloudCLI’s /setup page”.
2. Redo that step on /setup: 2. GitHub for git and gh, 1. Claude for Claude.
3. For a missing key, add it on the Runner’s Harness / Runtime page in Paperclip, under Environment variables. See Secrets.
4. Run the job again and read its log.

A task is also blocked when git pull fails at the start of a run, for example after someone rewrote the repo’s history. The summary shows git’s error.

The Runner is paused, and jobs wait

log ends with “Agent Runner is paused … its runs wait”.

Cause: Paperclip checks every new Claude agent with a short test run, and keeps it paused until Claude is signed in.

Fix: connect Claude in step 1. Claude of /setup. The page gives Paperclip the token and retries the Runner, with no redeploy.

A job doesn’t run on time

Ask Claude “which jobs do I have?” and check:

What list shows	Means	Fix
[paused]	The job is paused.	“Resume the digest.”
(off) after the schedule	Its schedule was turned off in Paperclip.	Turn it back on in Paperclip, on the job’s page.
run by hand only	The job has no schedule.	“Run the digest every weekday at 8:00.”
A time in another zone	The job has another time zone.	“Move the digest to 8:00 Toronto time.”

Also check:

• The last run was still working: a run that fires while the last one is still working is skipped. See No overlap, no backlog.
• The server was down at that time: missed runs are dropped, not replayed.
• The Runner is paused: see above.

A job ran twice, or cost more than expected

log shows a second agent run marked “follow-up of”.

Cause: the first run ended with its task still open, so Paperclip started another to close it.

Fix: ask Claude to make the skill end with “mark the task done with a one-line summary, or blocked with the reason”, then test it.

If two servers use the same repo and jobs, each runs them. Keep one. See Move to a new server.

“Not recorded” or “not pushed”

After a job change, the script’s last line says how the record went:

Line	Fix
Recorded in ...: commit 1a2b3c4, pushed.	Nothing to do.
... not pushed (...): push it.	Claude pulls and pushes; or push yourself in CloudCLI’s terminal. Check that you can push to the default branch.
Written to ..., not committed (...)	Claude commits and pushes it.
..., on branch X: merge it into main to keep the record there.	The clone is on another branch. Merge it, or switch back.
Not recorded: ... has no clone on this server	Add the repo on step 3 of /setup.
Not recorded: ... isn't readable	.claude/jobs.json isn’t valid JSON. Fix or delete it, then ask Claude to record your jobs.

“Which repo is this job for?”

Cause: you asked from a chat that isn’t in a connected repo, with several repos connected.

Fix: open a chat in the repo’s project in CloudCLI, or tell Claude the repo. To connect another repo, use step 3 of /setup.

If the chat’s repo isn’t connected at all, the script stops and asks to connect it on step 3, or to name a connected one.

The jobs skill can’t reach Paperclip

Message	Fix
Not connected to Paperclip: ... is missing.	CloudCLI connects at start. Redeploy CloudCLI, then check its log for [wiring] lines.
Paperclip at ... did not answer	Check that the Paperclip service is online in Railway.
Paperclip has no Runner agent yet	Paperclip creates it at start. Wait a minute and try again.

Setup page

Problem	Fix
“Claude didn’t accept that code”	The code is single-use and tied to its link. Press Start for a new link, then paste the new code.
“no token yet: check the code and paste it again”	Paste the whole code again, then Submit.
The GitHub code stays on the page	Enter it at github.com/login/device and authorize. The page updates once GitHub confirms.
“cloning failed” for a private repo	Connect GitHub first (step 2), then press Use this repo again.
“can’t list your repos”	Connect GitHub first, or type a public repo’s address.
Codex: device code sign-in is off	Turn it on in ChatGPT’s Security settings, then press Start again. See Codex.

CloudCLI says it is starting

“CloudCLI is starting. Try again in a moment.” shows while CloudCLI restarts, after a deploy or an update. The first start takes a few minutes, while it installs its tools.

Deploy fails, or a service keeps restarting

• The plan: the template needs Railway’s Hobby plan or above. Paperclip runs out of memory under a 1 GB limit.
• The password: it must be 8 to 128 characters.
• The logs: each service’s deploy log in Railway shows the template’s own lines, starting with [paperclip-cloudcli] and [wiring].

Still stuck

Open an issue on the template’s repo, mikedepo/paperclip-cloudcli. Say which commit your services run (the first line of their deploy logs) and what the log says. Never paste a token or a password.