Plugin Troubleshooting

The arvexa CLI returns a distinct exit code per outcome so a pipeline can tell "the package is wrong" from "the environment is wrong" from "retry might work":

• 0 — completed, and the answer was affirmative
• 1 — the CLI itself failed unexpectedly; a bug, not a user or host condition
• 2 — bad arguments, unknown command, missing required flag
• 3 — local contract validation rejected the package
• 4 — credential missing, malformed, revoked, or lacking a required scope
• 5 — DEVELOPER_PLATFORM_ENABLED is not "true" on the host
• 6 — the documented route does not exist on this host build
• 7 — the host answered with a structured error
• 8 — the request exceeded its time budget
• 9 — the request never produced a response
• 10 — CLI or host configuration is unusable
• 11 — the command ran and the verdict was negative (a scan or harness FAILED)

Exit 11 is deliberately not an error code. The request succeeded; the answer was no.

One wrapper caveat: pnpm run collapses every non-zero exit to 1, so a pipeline that branches on the codes above must invoke the binary rather than the script — ./node_modules/.bin/arvexa plugin validate ./my-plugin instead of pnpm arvexa plugin validate ./my-plugin.

Common failures, and what they actually mean:

• CREDENTIAL_MISSING — no key from stdin, the environment, or an apiKeyEnv reference. There is no --api-key flag by design.
• CREDENTIAL_MALFORMED — the value is not in arvexa_<prefix>_<secret> form, usually a truncated paste. Re-copy the show-once plaintext; it is not recoverable later.
• CONFIG_PLAINTEXT_CREDENTIAL — a credential field in arvexa.config.json. Remove it and use stdin or an environment reference.
• CONFIG_UNKNOWN_KEY — a typo in the config file. Allowed keys are baseUrl, appId, apiKeyEnv, and timeoutMs.
• PACKAGE_LAYOUT_MISSING — a required entry is absent. A plugin needs manifest.json, README.md, src/, and tests/.
• PACKAGE_LAYOUT_FORBIDDEN — a top-level entry outside the allowed five.
• NO_TEST_FILES — nothing runnable under tests/. The harness executes tests/*.js only.
• TESTS_IN_SRC — a file that looks like a test lives under src/, where the harness never looks.
• NON_JS_TEST_FILE — a .mjs, .cjs, or .ts file under tests/ that will never execute.
• ENTRYPOINT_SOURCE_MISSING — an entrypoint points at a path that is not in the package.
• MISSING_TEST — a declared entrypoint has no executed, non-skipped case. SKIPPED does not count.
• NONDETERMINISTIC — a replay disagreed. Something read the wall clock, randomness, or interpolated a varying value into a case name.
• UNAUTHORIZED_API_CALL — a capability call the broker denied: unknown operation id, undeclared scope, or a role/audience mismatch. Check arvexa catalog list.
• HOOK_SCOPE_MISSING — a declared hook requires a scope the manifest does not declare.
• HOOK_AUDIENCE_DENIED — a declared hook is not available to any declared audience.
• EXTENSION_POINT_ROLE_DENIED — an extension point is not allowed for the declared roles or audiences.
• SECURITY_SCAN_STALE — evidence expired, the policy version moved, or the manifest hash no longer matches the package.
• ENDPOINT_UNAVAILABLE — the host build does not serve the public Developer REST surface yet.
• FEATURE_DISABLED — the host has the Developer Platform flag off. It defaults to false and this is an operator change, not a CLI setting.
• PEER_UNAVAILABLE — the extension point bound successfully, but its peer is not wired in V1.

Two habits that prevent most of the above: run arvexa plugin validate before every pack, and run arvexa whoami when a credential behaves unexpectedly. whoami prints the masked key, the source it came from, and the granted scopes — and the most common "wrong key" incident is not a bad value but a stale ARVEXA_DEVELOPER_API_KEY shadowing the variable a project's apiKeyEnv names.