Appendix D. Troubleshooting

This appendix helps identify the next step when a tool fails or behaves unexpectedly. Use the symptom table to find the relevant explanation, then ask the agent to diagnose the problem. Tell it what you expected and what happened instead, and provide any error message it cannot already see. It should inspect the command, logs (recorded execution messages), and saved outputs before changing software or starting another copy of a job.

Symptom (links to help) First check for the agent
Command missing Whether the program is installed and this session can find it
Queued job stalled or failed Recorded status, whether the program is still running, and progress in its logs or outputs
Restored environment differs Actual software versions against recorded versions
Unexpected pipeline reruns The saved dependencies and which input or code files changed
Account access fails Whether the actual command uses the intended account, without printing secrets
Connected records missing Whether the connection can retrieve a known record and its attachment
Wrong browser session The browser profile and signed-in account
Headless agent fails The account, tools, inputs, and permissions supplied when that run starts
Local LLM fails Memory use, input length, and the original response or error
Agent-launched R stalls on macOS Whether the process is making progress and how it was launched
Cloud-synchronized files stall Synchronization activity and the locations of files being rewritten
PDF reports “No counter ‘none’ defined” The exact error and the document template

Have the agent diagnose, repair, and verify

A symptom can have several causes. For example, a queued fit that has produced no results may still be computing, may be unable to read its inputs, or may have failed before writing a file. Ask the agent to distinguish these possibilities using the running process, logs, and expected outputs. A process is a running instance of a program. High processor use alone does not establish whether that program is progressing or stuck.

Once the cause is understood, the agent should make a targeted correction and repeat the failed operation. For a long calculation, it can first use a small representative case through the same app, queue, or other execution method. It should check the resulting files as well as the reported status, then record lasting setup changes in the project context files, or in global user instructions if they apply across projects.1

Diagnose why [operation] produced [observed result] instead of [expected result]. Inspect the exact command, relevant logs, software setup, and outputs before changing anything. Check whether an earlier attempt is still running and making progress. Explain the likely cause and make a targeted correction, preserving existing work. Use a small representative check first if the full operation is expensive, then repeat the affected operation and inspect its output. Report what changed, what now works, and anything unresolved. Record lasting setup corrections in the project context files, or in global user instructions if they apply across projects. Ask me before changing research methods or inputs.

The sections below cover problems with running research code and building documents. For incorrect analyses, unsupported claims, or other problems with the research itself, see Appendix C: Troubleshooting in the companion guide Doing Research with AI Agents.

R launched by an agent on macOS

On some macOS setups, R can stall when an agent starts it without a terminal connection: the process uses a processor core but produces no output. If the agent identifies these symptoms, have it try a pseudo-terminal, a software-created terminal connection, and verify that the command finishes and produces the expected output.

Have the agent put the workaround in bin/rscript-pty, an executable helper: a small program that launches the project’s R commands with that connection. It changes how the analysis is started, without changing the analysis code. Ask the agent to check a small run through the method the project will actually use, including the queue if jobs will be queued. It should confirm that the expected output is produced and the process finishes before launching a long run.

Download the macOS R helper

Helper code and additional checks for targets, workers, and Quarto

Have the agent save this helper as bin/rscript-pty, make it executable, and use it for the project’s R commands. Keep its standard-input handling intact.2

#!/bin/sh
command -v script >/dev/null 2>&1 || {
  echo "No script command; cannot allocate a pseudo-terminal" >&2
  exit 127
}
exec script -q /dev/null Rscript "$@" < /dev/null

For targets, use callr_function = NULL and disable crew for the initial check so the work stays in the process with the terminal connection. Separately launched workers need their own verification. Retain the helper for queued R jobs too; success with one worker or queue configuration does not establish that another will behave the same way.

For Quarto that executes R, the macOS workaround wraps the complete render:

script -q /dev/null quarto render paper.qmd < /dev/null

Linux uses a different script interface, so this command should not be copied unchanged there. Appendix E: Terminal vocabulary explains terminal connections and program input.

If the agent’s sandbox prevents pseudo-terminal allocation, use an explicitly approved execution method or run the saved command from your own terminal. Do not silently turn off the restrictions. If a process stalls, have the agent identify it and inspect its progress before stopping it; launching a replacement without resolving the earlier attempt can leave both consuming resources.

Cloud-synchronized project storage

Git repositories and installed software environments can contain thousands of small files. Synchronizing frequent changes to these files through cloud-storage services such as Dropbox, Google Drive, or OneDrive can create heavy background activity and slow or block work on the project. A Git ignore rule controls what Git records; it does not control what a cloud-storage service synchronizes.

For an existing or stalled directory, first have the agent preserve the work and diagnose the synchronization state. Changing exclusions after a service has indexed thousands of files can itself trigger further synchronization work. There are two approaches:

  1. Exclude the affected folders from synchronization. This is the preferred option when the service supports keeping those folders locally without syncing them. Have the agent configure and verify the appropriate exclusion. For a new directory, it should do this before adding files. The mechanism depends on the service and platform; Dropbox documents its supported methods.
  2. Move the affected folders outside cloud storage. Use this option when suitable exclusions are unavailable or cannot resolve the problem. Have the agent move or recreate the affected items, configure the project to use their new locations, and check that its commands still work. It must preserve source files, uncommitted edits, and Git history.

The agent should target the folders causing the activity. For Git, this may be the .git/ directory that stores the repository’s history. A Python project’s .venv/ directory holds installed packages, while uv.lock records their versions. The installed environment can be excluded or recreated elsewhere while the version record and analysis source remain with the synchronized project. Chapter 6: Preserve a software environment: rig, renv, and uv explains software restoration.

After the repair, have the agent rerun the affected project command and, for a repository, confirm that its history and uncommitted changes remain intact. It should record any changed locations in the project context files and explain how excluded files are backed up or recreated.

PDF reports “No counter ‘none’ defined”

A PDF build can report “No counter ‘none’ defined” for a table without a caption when Pandoc emits a table setting that the installed packages expect to name an existing counter. For that specific error, have the agent add this guarded definition in the template’s preamble, the setup section before the document content begins:

\makeatletter
\@ifundefined{c@none}{\newcounter{none}}{}
\makeatother

The guard preserves a counter if it already exists. Have the agent rebuild the document and inspect the affected table. A different error may need a missing font, package, or source correction; this code block is not a general repair for failed PDF builds.

Footnotes

  1. See Chapter 7: Give the agent context for your project for project context files and Chapter 8: Apply your conventions across projects for global user instructions in Doing Research with AI Agents.↩︎

  2. Standard input is the input channel a program reads. The helper redirects it from /dev/null, which supplies no input. Retain that redirection as part of this workaround.↩︎