> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironrun.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Common ironrun Errors: Causes and Fixes for Developers

> Fixes for the most common ironrun errors: op not found, secret resolution failures, command timeouts, shell rejections, and agents ignoring run_sealed.

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.

<Tip>
  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](/troubleshooting/doctor) for details.
</Tip>

***

<AccordionGroup>
  <Accordion title="op: command not found">
    The 1Password CLI (`op`) isn't installed or isn't on your PATH.

    **Fix:** Install the 1Password CLI from [1password.com/downloads/command-line](https://1password.com/downloads/command-line/), then authenticate:

    ```bash theme={null}
    op signin
    ```

    After installing, confirm it's on your PATH:

    ```bash theme={null}
    op --version
    ```

    Then run `ironrun doctor` to confirm ironrun can see it.
  </Accordion>

  <Accordion title="secret resolution failed">
    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:

    ```bash theme={null}
    ironrun doctor
    ```

    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
  </Accordion>

  <Accordion title="command timed out">
    The command ran longer than the `ttl` configured in `ironrun.yml` and was killed.

    **Fix:** Increase the `ttl` for the command in `ironrun.yml`:

    ```yaml theme={null}
    commands:
      - id: slow-test
        argv: [go, test, ./...]
        ttl: 30m
    ```

    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`.
  </Accordion>

  <Accordion title="shell commands are not allowed">
    `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:

    ```yaml theme={null}
    # ✗ rejected
    - id: deploy
      argv: [bash, -c, ./scripts/deploy.sh]

    # ✓ correct
    - id: deploy
      argv: [./scripts/deploy.sh]
    ```

    If you're using `propose_command`, the same restriction applies — shell commands will be rejected with an error.
  </Accordion>

  <Accordion title="secret resolved to empty value — it cannot be redacted">
    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.
  </Accordion>

  <Accordion title="Agent ignores run_sealed and runs shell commands directly">
    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:

    ```bash theme={null}
    ironrun setup
    ```

    Then verify the instruction file contains something like:

    ```
    Use run_sealed for all commands that need credentials.
    Do not run printenv, cat .env, or echo $VAR.
    ```
  </Accordion>

  <Accordion title="ErrCIUntrusted in GitHub Actions">
    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.

    ```
    Error: runner: untrusted CI event — refusing to expose secrets: fork pull_request event from "owner/fork-repo"
    ```

    **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.
  </Accordion>

  <Accordion title=".env file refused: permissions too open">
    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:

    ```bash theme={null}
    chmod 600 .env
    ironrun import .env
    ```

    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.
  </Accordion>
</AccordionGroup>

***

For a systematic diagnosis of your full setup, see the [ironrun doctor reference](/troubleshooting/doctor).