Platform Troubleshooting

This page covers the most common itera.yml configuration mistakes for the platform integration.

Itera is ignoring my config file

Check these first:

• The file must live at the repository root.
• itera.yaml wins over itera.yml when both files exist.
• The top-level YAML value must be a mapping.

If you expected a nested apps/web/itera.yml file to work, move that config to the repository root and set project.root: apps/web instead.

commands.install.run or commands.install.script fails

This is expected current behavior. Install command text is managed by Itera.

Use these levers instead:

• project.packageManager to pin the package manager when auto-detection is ambiguous
• commands.install.cwd to choose where the managed install command runs

If an older draft told you to set commands.install.script: auto, remove that key entirely. The current parser rejects any non-empty install script value.

If you need a workspace-root install for a nested app, the usual fix is:

commands:
  install:
    cwd: repo_root

Strict mode is failing on missing commands

defaults.onMissing: strict disables fallback behavior when Itera cannot resolve required commands.

Typical fixes:

• add an explicit commands.dev.script
• add explicit quality.lint, quality.typecheck, and quality.format entries when your script names are non-standard
• set project.packageManager explicitly instead of relying on auto-detection
• keep infer_then_fallback if you want Itera to continue using built-in defaults

Strict mode does not let you bypass the managed install-command rules.

A command is running from the wrong directory

Use cwd deliberately:

• repo_root for workspace-root commands
• project_root for app-local commands
• a repo-relative path when neither constant is specific enough

Also check that:

• the directory already exists
• the path stays inside the repository
• you are not assuming project.root automatically moves install to the workspace root

If you set project.root: apps/web and still need a root-level install, add commands.install.cwd: repo_root.

My readyUrl is rejected

commands.dev.readyUrl must be a local HTTP readiness probe.

Valid examples:

• http://127.0.0.1:3000/
• http://localhost:4000/health

Invalid examples:

• https://localhost:3000/
• http://example.com/health
• http://user:pass@127.0.0.1:3000/

If you omit the field, Itera uses http://127.0.0.1:3000/ with a 120 second timeout.

Explicit run is rejected as unsafe

Iteration Service only accepts explicit run commands that stay within package-manager script execution.

Usually valid:

• npm run dev
• pnpm --filter web type-check
• yarn workspace client run lint
• bun run test

Usually invalid:

• python -c "print('hello')"
• multiline shell commands
• package-manager commands that are really install or exec operations instead of script execution

If you can express the command as a package script name, prefer script over run.

Product Agent did not use my dev or install settings

That is expected. Product Agent currently consumes a narrower policy subset than the full Iteration Service runtime contract.

What Product Agent cares about most:

• project.packageManager
• defaults.onMissing
• commands.quality.*
• request execution_policy.project_root
• request execution_policy.strict_mode
• request execution_policy.allowed_commands

What Iteration Service cares about:

• commands.install
• commands.dev
• readyUrl
• readyTimeoutSeconds

If the issue is in Product Agent execution policy, focus on the quality entries and request policy fields first. For everything else, check the itera.yml reference.