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 project base path for the app Itera should run against.
• itera.yaml wins over itera.yml when both files exist.
• The top-level YAML value must be a mapping.

If you expected a repository-root itera.yml file to configure a nested app automatically, move that config to the app's project base path or set project.root explicitly.

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 your config lives at the app's project base path and you 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.