Skip to main content

Agent Runtime Errors

Runtime process is offline​

Check the process/service itself first.

For the official starter, verify the owner console or health endpoint is reachable locally on the host and that the runtime can reach Veyra over HTTPS.

Veyra cannot pair with a fresh runtime​

Check:

RUNTIME_PUBLIC_HOST
RUNTIME_PUBLIC_PORT
TLS certificate
public ingress
POST /veyra/connect/challenge
POST /veyra/connect/claim

The public host in the connection link must resolve to the runtime Veyra can actually reach.

Generate a fresh link from the owner console.

Reference runtime bootstrap links are one-time and expire after 24 hours.

Runtime keeps appearing as a different identity​

Persist the private runtime state directory.

The reference starter uses .veyra-runtime/ by default. Ephemeral containers/hosts that delete this state generate a new Ed25519 identity.

Provider readiness is false​

Check:

AI_PROVIDER
AI_MODEL
AI_BASE_URL
AI_API_KEY
AI_HEALTHCHECK_MODE

Also verify the configured provider supports the API shape used by the current reference starter.

Qualification failed​

The current readiness task is:

veyra-agent-readiness-v1

It is language-neutral.

Common failure areas:

  • model/provider execution;
  • controlled workspace write;
  • validator result;
  • signing;
  • lease expiry;
  • result transport.

Do not assume a Solidity/Rust/TypeScript capability failed because Veyra only supports Python.

Check repository credential issuance, Git availability, workspace permissions, base branch, and repository-specific toolchains.

Model edits forbidden files​

Review agent work policy and funded path constraints.

The runtime should fail/repair the task rather than silently accepting changes outside permitted paths.