Troubleshooting

Start with the symptom you see, apply the check, then retry the smallest failed step.

Project creation fails

• Unsupported Node version: install Node 24 or newer, confirm with node --version, and run Creator again. Node 22.19 is not enough for this release.
• Installation fails: enter the retained project directory, run npm install, then continue with nylorun up, nylorun configure, and npm run dev.
• Setup is cancelled: Creator keeps files already written. Resume with the commands below.
• No interactive terminal: create the project, then start Runtime and configure it from an interactive terminal. Creator no longer has --skip-config. A non-interactive start without a stored host credential exits and names that setup. NYLORUN_DEV_MODEL=fixture skips the prompt.

cd my-agent
nylorun up
nylorun configure
npm run dev

The provider does not respond

• Run nylorun configure again against a running Runtime and verify the selected provider and model in the vault.
• Confirm the provider account has model access, quota, and valid billing.
• Read the Runtime log (nylorun logs) for the original error. Studio shows a safe terminal error and does not receive raw provider payloads.
• If you intended to seed the vault, confirm MODEL_PROVIDER and MODEL were set before the first start, and that MODEL_PROVIDER_API_KEY or a provider-native key was available. Custom providers also need MODEL_PROVIDER_BASE_URL. After the first write, change the vault — do not expect a later .env edit to replace it.
• See Models for vault and secret handling.

Port 8787 or 4161 is already in use

Set --port or PORT to change Runtime's listen port. Start Studio separately:

nylorun up --port 8788
npm run dev -- --no-autostart --port 8788
nylorun studio --runtime-url http://127.0.0.1:8788 --studio-port 4162

PORT must be an integer from 1 through 65535. The 0.13 default of 3000 no longer applies. If status says port-conflict, another Runtime already owns that port — use nylorun runtime status / nylorun down.

Development does not start

• tsx is missing: install tsx in the project; nylorun dev loads agents/index.ts with project-local tsx.
• Studio is missing: install @nylorun/studio as a development dependency or run npm run dev -- --no-studio.
• .env is still a directory: back it up and write a file only if you need a one-time vault seed. Move leftover OAuth credentials to .nylorun/auth.json. See Migrate from 0.13.
• The project still exports a Hono app: this release has no export default app. Export agents from agents/index.ts and install @nylorun/cli.
• nylorun start is not a command: use nylorun serve.
• nylorun configure exits 6: start Runtime first (nylorun up).
• The readiness check times out: fix compile or startup errors in the Runtime/CLI terminal and confirm http://127.0.0.1:8787/health or /v1/agents (with the local server credential) responds. Use the configured PORT when it is not 8787.

Studio cannot find the agent

• Confirm Runtime is up: nylorun runtime status.
• nylorun studio resolves the active scope. Use --runtime-url only to override it.
• Use npm run dev or nylorun serve so the CLI registers manifests and provisions credentials. Attaching Studio to a process you started some other way requires the project's local server credential (or NYLORUN_SERVER_KEY).
• Keep Runtime and Studio on the same development machine.

Changes do not appear

Check the terminal for a compile error. If the stack is healthy, start a new Studio session after definition or implementation edits — live upgrades are not supported. Source changes re-register agents and reconnect the executor; they do not restart Runtime.

• History disappears after deleting .nylorun/: local SQLite, vault, and credentials live there.
• Old JSONL sessions do not resume: SessionRecord / events.jsonl roots are archive. They are not converted to SQLite checkpoints.
• In-flight turns failed after upgrade: schema 3 turns and old hook actions are cancelled on Runtime startup. Start new sessions. See 0.15 → 0.17.

Model selection remains in config/ or .env/

The vault takes precedence after the first host-model write. Runtime does not move or delete leftover .env/model.json and config/model.json files. If nylorun reports that .env is a directory, migrate it manually—do not leave a directory named .env in a project that uses the CLI.

Still blocked?

Search the docs, inspect the terminal error, then open a focused issue in the Harness repository with your Node version, command, expected result, and redacted error output.