Configuration Validation Best Practices

Required Structure

Here's a complete, valid fabrcore.json with the minimum required sections:

{
    "ModelConfigurations": [
        {
            "Name": "OpenAIProd",
            "Provider": "openai",
            "ModelId": "gpt-4o",
            "ApiKeyAlias": "openai-key"
        }
    ],
    "ApiKeys": [
        {
            "Alias": "openai-key",
            "Key": "sk-..."
        }
    ]
}

The two critical arrays are ModelConfigurations and ApiKeys. Each model configuration references an API key by alias, and each API key entry provides the actual credential. This indirection lets multiple model configurations share the same key without duplicating it.

Common Mistakes

These are the configuration errors we encounter most frequently:

1. ApiKeyAlias doesn't match any ApiKeys[].Alias

This is the most common mistake. The ApiKeyAlias in your model configuration must exactly match an Alias in the ApiKeys array — case-sensitive. If you have "ApiKeyAlias": "openai-key" but your ApiKeys entry has "Alias": "OpenAI-Key", FabrCore won't find it and the agent will fail to initialize.

// Model config references "openai-key"
"ApiKeyAlias": "openai-key"

// But ApiKeys has "OpenAI-Key" — case mismatch!
"Alias": "OpenAI-Key"

2. Missing ModelConfigurations array entirely

If you define agents but forget the ModelConfigurations array, every call to GetChatClient() or CreateChatClientAgent() will fail. The error message mentions the model config name but doesn't always make it obvious that the entire array is missing.

3. Placeholder API key values

Leaving "Key": "sk-..." or "Key": "your-key-here" in the config is easy to overlook. FabrCore doesn't validate key formats at startup — it passes the key to the provider, which returns an authentication error. The error comes from the provider SDK, not FabrCore, so it can be confusing.

4. Malformed JSON

Trailing commas, missing quotes around property names, or single quotes instead of double quotes. JSON is strict — use a linter or your IDE's JSON validation before deploying.

Validation Checklist

Before running your FabrCore application, walk through this checklist:

1. Parse the JSON. Run your fabrcore.json through a JSON validator. Fix any syntax errors before anything else.
2. Verify ModelConfigurations exists and contains at least one entry. Each entry needs Name, Provider, ModelId, and ApiKeyAlias.
3. Verify ApiKeys exists and contains entries for every ApiKeyAlias referenced by your model configurations.
4. Check alias matches. For each ApiKeyAlias, confirm an exact case-sensitive match exists in ApiKeys[].Alias.
5. Confirm real API keys. Ensure no placeholder values remain. If using environment variables, verify they're set in your runtime environment.
6. Validate agent references. If agents reference model configs by name (e.g., "Models": "OpenAIProd"), confirm those names exist in ModelConfigurations[].Name.

Environment Variables

Hardcoding API keys in fabrcore.json works for local development, but you should use environment variables for anything beyond your dev machine:

{
    "ApiKeys": [
        {
            "Alias": "openai-key",
            "Key": "${OPENAI_API_KEY}"
        }
    ]
}

FabrCore resolves ${VARIABLE_NAME} patterns in key values at startup. This keeps secrets out of your config file and lets you use different keys per environment — development, staging, production — without maintaining separate config files.

For container deployments, pass environment variables through your orchestrator's secret management (Kubernetes secrets, Azure Key Vault references, Docker secrets). The config file stays the same across environments; only the environment variables change.

Full Reference

For the complete configuration schema — including agent definitions, plugin bindings, MCP server connections, and storage settings — see the configuration documentation.