# Recover a stuck reference job This guide recovers a reference job whose clip failed and whose fallback inbox write also failed. `bob ref jobs run` retries that fallback write without clipping the URL again. There is no separate retry or delete subcommand. ## Before you start Install the CLI. Ref jobs live in the user state spool (`${XDG_STATE_HOME:-~/.local/state}/bob-cli/ref/jobs/`), not in the vault. `bob ref jobs` lists that spool; it does not select `BOB_DIR`. ## 1\. Inspect job state ``` bob ref jobs bob ref doctor ``` Pending, clipping, and stuck jobs always show. `bob ref doctor` prints a `ref jobs:` row with pending and stuck counts and warns when any job is stuck, with the hint `bob ref jobs run`. Confirm a `stuck` row and note its display URL. `bob ref jobs -f json` is the machine-readable form. `worker.log` holds the detached worker's stdout and stderr. A `clipped` (queued) job is already finished in the spool; drain it with `bob ref scan -i`, not another worker pass. ## 2\. Run the worker ``` bob ref jobs run ``` The worker holds `worker.lock`. A second run prints `another clip worker is running` and exits 0. For a stuck job it retries the fallback write only. Confirm a line for that URL and a summary that is not `nothing to do`. Exit 1 means the fallback write failed again; the job stays in `stuck/` with both errors. A pending job older than an hour usually means the capture kick never ran; the same `bob ref jobs run` clips those pending jobs (one attempt, then fallback on failure). ## 3\. Confirm recovery ``` bob ref jobs ``` Confirm the stuck row is gone. A successful fallback writes the original URL task into the job's parent note plus a ⚠️ child with `retry: bob ref create -P `. Open that note and confirm the task line. To clip the URL now, run the printed `bob ref create` command; that inline import does not use this spool. ## If it goes wrong If the job is still `stuck`, read `worker.log` and the ⚠️ reason, fix the parent note path or vault lock, and run `bob ref jobs run` again. Do not delete files under `ref/jobs/stuck/` by hand. If the same URL is pending for another vault, wait for that job to finish or import with `bob ref create --bob-dir /path/to/vault-b ''`. ## Related - [Ref jobs]() - [Save a link to your reading queue]() - [bob ref]() - [Reference library]()