Server will not start

AXL fails the boot on several classes of bad configuration rather than starting in a state that would misbehave later. That is intentional, and the error usually names the offender.

Things that deliberately fail startup:

• An unknown middleware name, or settings that do not type-check. A typo in [middleware.tool_cache] is rejected rather than silently ignored, as is a limiter configured with no limit.
• A fallback model list containing an unknown model, or the same model twice. See LLM failover.
• A content-safety guard whose API-key environment variable is missing. See Configure the shield.
• A shielded agent with no PII_VAULT_KEY. Without the key, redacted values are never persisted and tokenized history is permanently unrestorable - a data-loss mode, so the boot refuses instead. Set PII_VAULT_KEY to CSPRNG key material (e.g. openssl rand -hex 32; the 32-byte key is derived from it), or disable the shield for every agent.
• A production instance with no /mcp host allowlist. MCP_ALLOWED_HOSTS (or PUBLIC_BASE_URL, from which it is derived) must be set when RUST_ENV=production; without it the /mcp endpoint accepts only loopback Host headers and would silently reject every external MCP request.

Check the resolved middleware stack for an agent without starting the server:

axl weave print --config axl-config/agents/<agent>/agent.toml

That runs the same validation the boot runs, so a name or setting it rejects is the one to fix.

Next

• Middleware - valid names and settings.
• LLM failover - the fallback list rules.