Skip to main content
This page covers the most common errors you’ll encounter with ironrun and how to fix them. When something goes wrong, start with ironrun doctor — it catches most of these problems in one command before you dig into individual symptoms.
Run ironrun doctor first. It validates your policy, checks provider authentication, verifies the redaction engine, and confirms that every command’s binary is on your PATH — all in one shot. See the doctor reference for details.
The 1Password CLI (op) isn’t installed or isn’t on your PATH.Fix: Install the 1Password CLI from 1password.com/downloads/command-line, then authenticate:
After installing, confirm it’s on your PATH:
Then run ironrun doctor to confirm ironrun can see it.
ironrun couldn’t retrieve a secret from the configured provider. This could mean the provider CLI isn’t installed, your credentials have expired, or the secret reference in ironrun.yml is wrong.Fix: Run ironrun doctor — it validates the policy and checks that your provider is installed and authenticated:
Note that ironrun validate only parses the policy file. It does not check provider authentication. Use ironrun doctor when you’re debugging a resolution failure.Common causes:
  • Provider CLI not installed or not on PATH (e.g., op, vault, doppler, infisical)
  • Expired credentials — re-run op signin, vault login, etc.
  • Typo in the secret reference path in ironrun.yml
  • Wrong environment or project name in the reference
The command ran longer than the ttl configured in ironrun.yml and was killed.Fix: Increase the ttl for the command in ironrun.yml:
Set ttl: 0 to disable the timeout entirely — use this carefully, as it means the command can run indefinitely. For interactive commands like dev servers you typically want ttl: 0.
argv[0] is sh, bash, zsh, or another shell interpreter. ironrun rejects shell invocations by design — they can re-expand secrets through variable substitution and pipes, defeating the redaction layer.Fix: Wrap the shell logic in a script file and invoke the script directly:
If you’re using propose_command, the same restriction applies — shell commands will be rejected with an error.
The provider returned an empty string for a secret. ironrun refuses to proceed because an empty redaction pattern would match everything.Fix: Check the secret reference in ironrun.yml. Common causes:
  • Typo in the 1Password item or field name
  • Environment variable name doesn’t match what’s in the envfile
  • The secret exists in a different environment or vault
After fixing the reference, run ironrun doctor to confirm resolution works before trying again.
The agent is invoking commands through a raw shell (bash -c, the Bash tool, etc.) instead of calling run_sealed. This bypasses ironrun entirely — secrets injected by the agent’s shell environment are not redacted.Fix: Check that the agent instruction file exists in your project root:
  • Claude Code: CLAUDE.md
  • Codex: CODEX.md or AGENTS.md
  • Cursor: .cursorrules
The file must contain explicit instructions to use run_sealed for all commands that touch credentials. Agents respect these files strongly for explicit directives.If the file is missing or doesn’t mention run_sealed, re-run ironrun setup to regenerate it:
Then verify the instruction file contains something like:
A pull request from a fork tried to access secrets and ironrun blocked it. This is correct behavior — fork PRs can’t be trusted with your production credentials.
Why this is correct: A fork PR can modify the workflow file. If ironrun allowed it to access secrets, an attacker could exfiltrate your credentials by opening a PR.If you need to test in a fork: Set IRONRUN_ALLOW_PRT=1 only if you fully understand the security implications and have reviewed the PR code. In most cases, you should not need this — run tests against a dedicated staging environment instead, using the pull_request_target event with strict conditions.
ironrun refused to import a .env file because it’s readable by users other than the owner.Fix: Tighten the file permissions and retry the import:
ironrun enforces owner-only permissions (600) on .env files before importing them. This prevents other users or processes on the machine from reading your secrets through the plaintext file.
For a systematic diagnosis of your full setup, see the ironrun doctor reference.