Common Rejection Errors · Developers Hub

Use this cookbook when an extension fails to parse, load, register, migrate, expose an action, resolve a MIC type, register a mail transport, or respond to API/MCP calls.

Human Path

Start from the layer that failed:

Validate local files and run the relevant test.
Review the Installed Extensions surface at /extensions.
Confirm the extension is registered, enabled, and granted its manifest scopes.
Confirm the caller holds the action scope.
Use /api/v1/manifest or MCP tools/list only after the extension has loaded.

AI Path

An AI coding agent can inspect files, fix local PHP/JSON mistakes, and run verification commands.

An installed MCP client can remediate only through exposed runtime tools it is already allowed to call. It cannot edit local extension files, register itself, broaden its own scopes, enable extensions, or bypass hidden MCP policies.

Quick Triage Order

Layer	Check first	Verification
Manifest	JSON shape, vendor, scope list, admin routes	`php app/tests/verify-extension-system-foundation.php`
Grant/load	Registered, enabled, granted, latest load error	`/extensions`
Action	URI, domain, schemas, `requiredScope`, `exposeToMcp`	`/api/v1/manifest`, direct API call
MCP	Caller scopes and tool exposure	MCP `tools/list`
Migration	`{vendor}_*` table isolation	Foundation test or load error
MIC	Descriptor slug, bank surface, picker URL	`php app/tests/verify-content-banks-mic.php`
Mail	Transport slug, descriptor, active transport	`php app/tests/verify-forms-mail-substrate.php`

Manifest Rejections

Error surface	Likely cause	Safe remediation	Do not bypass
`Extension manifest not found.`	Missing `manifest.json`.	Add it at `app/extensions/{vendor}/manifest.json`.	Do not register actions outside the loader.
`Extension manifest is not valid JSON.`	Malformed JSON or non-object root.	Fix JSON syntax and keep an object root.	Do not parse it manually in bootstrap.
`Extension vendor must be snake_case.`	Vendor violates `^[a-z][a-z0-9_]*$`.	Use lowercase snake_case.	Do not rely on display names as vendor ids.
`Extension vendor must match its directory name.`	Manifest vendor does not equal normalized directory.	Align directory and manifest vendor.	Do not fake the expected vendor in code.
`Extension name is required.`	`name` is absent or empty.	Add a non-empty name.	Do not use an empty name for test-only packages.
`Extension version is required.`	`version` is absent or empty.	Add a non-empty version.	Do not encode version only in README.
`Extension requiredScopes must be a list.`	`requiredScopes` is not an array.	Use a JSON array.	Do not split strings in bootstrap.
`Extension manifest declares unknown scope: ...`	Scope is outside base extension scopes.	Use a supported base scope or evaluate scope expansion.	Do not invent sub-scopes in the manifest.
`Extension adminRoutes must be a list.`	`adminRoutes` is not an array.	Use `[]` or route objects.	Do not mount routes outside the manifest.
`Extension adminRoutes entries must be objects.`	Route entries are scalars.	Use objects with `key` and `path`.	Do not infer route paths from strings.
`Extension admin route keys must be kebab-case.`	Key contains invalid characters or starts incorrectly.	Use lowercase route keys such as `settings`.	Do not use route keys for permission checks.
`Extension admin route paths must be relative paths.`	Path is empty, absolute, or contains `..`.	Use a package-local relative path.	Do not route to core files or parent directories.

Action Registry Rejections

Error surface	Likely cause	Safe remediation	Do not bypass
`Extension vendor must be snake_case.`	Loader tried to register with invalid vendor.	Fix the manifest/directory vendor.	Do not register the action as core.
`Extension action URI must start with /api/v1/x/{vendor}/.`	Action URI is outside the vendor API namespace.	Use `/api/v1/x/my_vendor/...`.	Do not claim a core API route.
`Extension action domain must start with x.{vendor}.`	Metadata domain is not vendor-owned.	Use `x.my_vendor.resource`.	Do not use core action domains.
`Extension action inputSchema must be non-empty.`	`inputSchema` is `[]`.	Use an object schema, even for no-input actions.	Do not omit schema to skip validation.
`Extension action outputSchema must be non-empty.`	`outputSchema` is `[]`.	Declare the result object shape.	Do not leave AI clients guessing result shape.

Migration Rejections

Error surface	Likely cause	Safe remediation	Do not bypass
`Extension migration vendor must be snake_case.`	Migration runner received an invalid vendor.	Fix the extension vendor.	Do not construct tracking tables manually.
`Extension migrations may only modify tables prefixed with {vendor}_.`	SQL list migration touches a core or cross-vendor table.	Rename tables to `{vendor}_...` and keep storage isolated.	Do not mutate core tables from extension migrations.
`Failed to prepare extension migration SQL statement.`	SQL could not be prepared.	Fix SQL syntax for the configured database.	Do not mark the migration as applied manually.
Load error during callable migration	Callable threw while running.	Fix the callable and preserve vendor-owned storage.	Do not use callable migrations to hide core-table mutation.

MIC Rejections

Error surface	Likely cause	Safe remediation	Do not bypass
`Core mic slug must be non-empty and must not use the x.* namespace.`	Core registration used extension namespace.	Use core slug only for core code.	Do not register extension types as core.
`Extension mic vendor and slug are required.`	Vendor or local slug is empty.	Provide both.	Do not build descriptors with empty slugs.
`Extension mic slug must be the local slug, not the fully-qualified x.* slug.`	Bootstrap returned `x.vendor.slug` as the key.	Return local slug such as `catalog`.	Do not double-prefix extension MIC types.
`Mic element type is already registered: ...`	Duplicate slug.	Use one resolver per slug.	Do not override another type.
`Mic resolver descriptor slug must match the registered slug.`	`describe()` returns a different slug.	Match `x.{vendor}.{slug}` after extension registration.	Do not rely on display label for identity.
`Picker mic types require parentSurfaceUrl.`	Descriptor uses `bankSurface: picker` without URL.	Provide an admin parent surface URL.	Do not expose an orphan picker entry.
`Mic bankSurface must be editor, picker, or none.`	Descriptor uses unsupported visibility.	Use one of the three supported values.	Do not invent bank surfaces in docs.
`Mic slug must be lowercase and namespaced extensions must use x.{vendor}.{slug}.`	Slug format is invalid.	Use lowercase slug conventions.	Do not mix public labels and slugs.

Mail Transport Rejections

Error surface	Likely cause	Safe remediation	Do not bypass
`Core mail transport slug must be snake_case.`	Core slug format invalid.	Use lowercase snake_case.	Do not register provider extensions as core transports.
`Extension mail transport vendor and slug must be snake_case.`	Extension transport vendor or slug has invalid format.	Use `my_vendor` and `resend` style slugs.	Do not use provider display names as ids.
`No active mail transport is registered.`	Active slug is not present in registry.	Ensure core SMTP or the selected transport is registered before sending.	Do not silently drop mail.
`Mail dispatch failed.`	Active transport returned failed result.	Return a stable non-secret error and fix provider configuration.	Do not expose provider secrets in the error text.

Grant And Load Rejections

Error surface	Likely cause	Safe remediation	Do not bypass
`Unknown extension scope: ...`	Grant repository received a scope outside the base extension list.	Grant only supported base scopes.	Do not write directly to `extension_scope_grants`.
`Vendor must be snake_case.`	Grant repository received invalid vendor.	Align vendor with manifest and directory.	Do not store aliases as vendors.
`Extension requires ungranted scope: ...`	Manifest requires a scope the operator did not grant.	Operator reviews and grants or removes the manifest need.	Do not weaken the manifest just to load.
Latest load error shows bootstrap exception	`bootstrap.php` or included code threw.	Fix local code and reload.	Do not suppress all exceptions in bootstrap.
Extension remains absent from action catalog	Unregistered, disabled, under-granted, or failed load.	Check `/extensions` and latest load error.	Do not call action classes directly.

Dispatcher, Auth, Scope, And Rate Errors

Code	HTTP status	Likely cause	Safe remediation	Do not bypass
`action_not_found`	404	No action matched method and URI.	Check load state, URI, method, and namespace.	Do not infer a different route.
`auth_required`	401	Private action has no session or bearer caller.	Use an authenticated caller.	Do not document private actions as public.
`auth_invalid`	401	Bearer token malformed, unknown, revoked, or production-disallowed.	Use an operator-provisioned active token.	Do not fall back to hard-coded secrets.
`scope_insufficient`	403	Caller lacks `requiredScope`.	Use a caller with the required scope or ask operator to review grants.	Do not broaden the caller from inside the action.
`input_invalid`	400	Required field missing or type mismatch.	Fix request shape according to `inputSchema`.	Do not relax schema to accept ambiguous input.
`rate_limited`	429	AI integration exceeded its request budget.	Back off and retry after the window.	Do not parallel-retry or mint a new trust gate.
`uncaught_exception`	500	Action threw unexpectedly.	Fix known failures to return declared errors.	Do not hide the exception by returning false success.
Declared action error	422	Action returned `MyronActionResult::error()`.	Satisfy the named precondition or business rule.	Do not treat it as a protocol failure.

MCP-Specific Symptoms

Symptom	Likely cause	Safe remediation
Tool missing from `tools/list`	Action is not loaded, `exposeToMcp:false`, or caller lacks scope.	Check load state, metadata, and caller scope.
`tools/call` cannot find a tool	Client inferred or cached the name.	Use the exact name from `tools/list`.
MCP auth error	Dispatcher returned auth or scope failure.	Fix caller identity or operator-granted scopes.
MCP `isError:true`	Tool reached the action and the action returned a declared failure.	Read the failure and satisfy the precondition.

Scopes

This page requires no runtime scope to read.

Runtime calls still require the relevant action scope. Manifest and grant workflows use base extension scopes. Admin enable/disable/grant changes remain human-admin workflows.

Artifacts

Useful artifacts while troubleshooting:

manifest.json
bootstrap.php
action classes and metadata,
migration files,
MIC resolver descriptors,
mail transport descriptors,
/extensions load state,
/api/v1/manifest,
MCP tools/list,
action envelope actionId and auditEventId.

Safety Boundary

Fix the failing layer. Do not bypass it. A rejection is usually the guardrail working: namespace isolation, storage isolation, operator grants, caller scopes, schema validation, MCP exposure, and rate limits are all part of the extension safety model.

Verification

Run the most specific check:

php app/tests/verify-extension-system-foundation.php
php app/tests/verify-content-banks-mic.php
php app/tests/verify-forms-mail-substrate.php

For runtime action availability, verify with the scoped direct API path and then MCP tools/list/tools/call.

Failure Modes

Failure	What it means	Safe response
Same error persists after local edits	Runtime may still be using a stale load state or the wrong file changed.	Re-run verification and re-check `/extensions`.
Fix requires new API/MCP behavior	The docs or extension need capability expansion.	Stop and start a fresh Evaluate and Contract cycle.
Remediation asks AI to grant itself scope	Trust boundary was violated.	Route grant changes through a human administrator.
Error message contains a secret	Error handling is unsafe.	Replace with a stable non-secret diagnostic.