Troubleshooting

Validation errors

Schema error: 'version' is a required property

Cause: Your schema.json is missing the required version field.Solution: Add "version": "1.0" to the top level of your schema:

{
  "version": "1.0",
  "type": "object",
  "properties": {
    // your options
  }
}

Schema error: 'description' is a required property

Cause: One or more options in your schema are missing the description field.Solution: Add a description to every option:

"my.option": {
  "type": "string",
  "default": "value",
  "description": "Human-readable description of this option"
}

Property 'option.name' default value does not match schema

Cause: The default value doesn’t match the declared type.Common examples:

// Wrong: string for integer type
{"type": "integer", "default": "42"}

// Right:
{"type": "integer", "default": 42}

// Wrong: float for integer type
{"type": "integer", "default": 5.5}

// Right:
{"type": "number", "default": 5.5}

// Wrong: unquoted string
{"type": "string", "default": hello}

// Right:
{"type": "string", "default": "hello"}

Solution: Ensure the default value matches the type:

integer - whole numbers only (no decimals)
number - any numeric value (integers or decimals)
string - quoted strings
boolean - true or false (unquoted)
array - arrays with items matching items.type

Additional properties are not allowed ('extra' was unexpected)

Cause: Your schema includes fields that aren’t part of the sentry-options specification.Solution: Remove extra fields. Only these fields are allowed per option:

type (required)
default (required)
description (required)
items (required only for array types)

// Wrong:
"my.option": {
  "type": "string",
  "default": "value",
  "description": "Description",
  "example": "example value",  // Not allowed
  "format": "email"            // Not allowed
}

// Right:
"my.option": {
  "type": "string",
  "default": "value",
  "description": "Email address for notifications"
}

Value error: Additional properties are not allowed

Cause: Your values.yaml file contains option keys that don’t exist in the schema.Error shows which key is unknown:

Value error for seer:
  unknown.option Additional properties are not allowed

Solution: Either add the option to your schema, or remove it from values.yaml. Check for typos:

# Wrong (typo in option name):
options:
  feature.enabeld: true  # Should be 'enabled'

# Right:
options:
  feature.enabled: true

Unknown namespace 'X': No schema found

Cause: You have values files for a namespace that doesn’t exist in the schemas directory.Solution:

Check that the namespace exists in your schemas directory
Verify the namespace name matches exactly (case-sensitive)
For automator repo: Ensure repos.json includes the service repo and SHA is up to date

# Fetch latest schemas from repos.json
sentry-options-cli fetch-schemas --config repos.json --out schemas/

Invalid {label} 'name': character 'X' not allowed

Cause: Namespace or target name contains invalid characters.Rules:

Lowercase alphanumeric, -, or . only
Must start and end with alphanumeric

Solution:

# Invalid:
MyService    # Uppercase not allowed
my_service   # Underscores not allowed
-service     # Cannot start with hyphen
service.     # Cannot end with dot

# Valid:
myservice
my-service
my.service
a1-b2.c3

Namespace 'X' is invalid. Expected either 'Y' or 'Y-*'

Cause: Namespace doesn’t follow the required naming convention for the repository.Solution: Rename the namespace directory to match either:

Exact repo name: seer
Repo name with suffix: seer-autofix, seer-grouping

# For the 'seer' repo:

# Valid:
sentry-options/schemas/seer/
sentry-options/schemas/seer-autofix/
sentry-options/schemas/seer-grouping/

# Invalid:
sentry-options/schemas/autofix/  # Missing 'seer-' prefix

Duplicate key 'option.name' found in file1.yaml and file2.yaml

Cause: The same option key appears in multiple YAML files within the same target directory.Solution: Remove the duplicate. Each option can only be defined once per target:

option-values/seer/default/
├── core.yaml
│   └── feature.enabled: true      # Defined here
└── features.yaml
    └── feature.enabled: false     # ❌ Duplicate!

Either remove from one file or consolidate related options into a single file.

Namespace 'X' is missing required 'default' target

Cause: Every namespace must have a default/ directory with at least one values.yaml file.Solution: Create the default target:

mkdir -p option-values/myrepo/default
cat > option-values/myrepo/default/values.yaml << 'EOF'
options:
  my.option: value
EOF

Schema evolution errors

Namespace 'X' was removed

Cause: You deleted a namespace directory from your schemas.Solution: Namespace removal is a breaking change. You must:

Remove all references from ops repo (pod annotations)
Remove all code using the namespace
Remove values from sentry-options-automator
Contact DevInfra to coordinate schema removal

Temporary workaround: Restore the namespace directory to unblock your PR.

Option 'namespace.option' type changed from 'X' to 'Y'

Cause: You changed the type field of an existing option.Solution: Type changes are breaking. Instead, add a new option:

{
  "old.option": {
    "type": "integer",
    "default": 100,
    "description": "[DEPRECATED] Use new.option instead"
  },
  "new.option": {
    "type": "number",
    "default": 100.0,
    "description": "New option with decimal support"
  }
}

Then migrate code to use the new option and eventually remove references to the old one.

Option 'namespace.option' default value changed from X to Y

Cause: You changed the default field of an existing option.Solution: Default changes are breaking because services may rely on schema defaults before ConfigMaps are deployed.Workaround:

Deploy new values to all targets in sentry-options-automator first:

# option-values/myrepo/default/values.yaml
options:
  my.option: new_value  # Override the default

Wait for ConfigMaps to propagate (~2 minutes)
Verify all regions are using the new value
Now you can add a new option with the desired default

Option 'namespace.option' array items type changed from 'X' to 'Y'

Cause: You changed the items.type field of an array option.Solution: Same as type changes - add a new option instead:

{
  "ids": {
    "type": "array",
    "items": {"type": "integer"},
    "default": [1, 2, 3],
    "description": "[DEPRECATED] Use ids.v2"
  },
  "ids.v2": {
    "type": "array",
    "items": {"type": "string"},
    "default": ["1", "2", "3"],
    "description": "IDs as strings for compatibility"
  }
}

Runtime errors

Values directory does not exist: /etc/sentry-options/values

Cause: The client library cannot find the values directory.Common scenarios:

ConfigMap not mounted - Pod annotations missing or incorrect
ConfigMap doesn’t exist - Not yet deployed to this cluster
Wrong SENTRY_OPTIONS_DIR - Environment variable pointing to wrong path

Solution:Check pod annotations:

annotations:
  options.sentry.io/inject: 'true'
  options.sentry.io/namespace: myrepo

Check ConfigMap exists:

kubectl get configmap sentry-options-myrepo

Check mount in pod:

kubectl exec -it mypod -- ls -la /etc/sentry-options/values/

Suppress error (if ConfigMap is optional):

export SENTRY_OPTIONS_SUPPRESS_MISSING_DIR=true

Failed to read directory /etc/sentry-options/values: Permission denied

Cause: The pod doesn’t have read permissions on the mounted volume.Solution: Ensure the ConfigMap volume is mounted as readOnly: true (default behavior with injector). Check your pod security context:

securityContext:
  runAsNonRoot: true
  runAsUser: 1000  # Ensure user can read mounted files

Options not updating after ConfigMap change

Cause: Hot-reload not detecting file changes.Checklist:

Wait 2 minutes - ConfigMap propagation takes ~60-90 seconds, plus 5 second poll interval
Check ConfigMap was actually updated:

kubectl get configmap sentry-options-myrepo -o yaml

Check file mtime in pod:

kubectl exec -it mypod -- stat /etc/sentry-options/values/myrepo/values.json

Check watcher thread is alive - Look for errors in application logs
Restart pod as workaround:

kubectl rollout restart deployment/myrepo

Value error: "not-a-number" is not of type "integer"

Cause: A value in your values.yaml doesn’t match the schema type.Solution: Fix the type mismatch in values.yaml:

# Wrong:
options:
  rate.limit: "100"  # String instead of integer

# Right:
options:
  rate.limit: 100    # Integer (no quotes)

Type reference:

Integers: 42 (no quotes, no decimals)
Numbers: 3.14 or 5 (no quotes)
Strings: "hello" (quoted)
Booleans: true or false (no quotes)
Arrays: [1, 2, 3] or ["a", "b"]

Local development issues

Options not loading in local development

Cause: The client library can’t find your local sentry-options directory.Solution:

Ensure correct directory structure:

project-root/
├── sentry-options/
│   ├── schemas/
│   │   └── myrepo/
│   │       └── schema.json
│   └── values/
│       └── myrepo/
│           └── values.json  # Create this for local testing
└── your-code/

Create local values.json:

mkdir -p sentry-options/values/myrepo
cat > sentry-options/values/myrepo/values.json << 'EOF'
{
  "options": {
    "my.option": "local-value"
  }
}
EOF

Run from project root or set SENTRY_OPTIONS_DIR:

export SENTRY_OPTIONS_DIR=/path/to/sentry-options
python your_script.py

Hot-reload not working locally

Cause: Local filesystem events may not trigger mtime updates properly on some systems.Solution:

Modify the values.json file (not a symlink)
Wait 5 seconds for the next poll cycle
Check file was actually modified:

stat sentry-options/values/myrepo/values.json

If using Docker: Ensure volumes are properly mounted and not using certain drivers that don’t propagate mtime changes

CI/CD issues

CI failing: 'fetch-schemas failed'

Cause: The CLI cannot fetch schemas from repos.json.Common causes:

Invalid SHA in repos.json - Commit doesn’t exist or was force-pushed
Network issues - Cannot reach GitHub
Invalid repo URL
Wrong path - Schema directory doesn’t exist at that path in the repo

Solution:

# Verify the SHA exists:
git ls-remote https://github.com/getsentry/myrepo | grep abc123

# Verify the path is correct:
# Should contain: sentry-options/schemas/{namespace}/schema.json

Update repos.json with correct SHA and path.

CD failing: 'ConfigMap exceeds maximum size'

Cause: ConfigMaps have a 1MB size limit.Solution:

Split the namespace - Create multiple namespaces (e.g., myrepo-core, myrepo-features)
Reduce option count - Remove unused options
Shorten option names and descriptions

Check current size:

sentry-options-cli write \
  --namespace myrepo \
  --target default \
  --output-format configmap | wc -c

Pods failing to start after adding annotations

Cause: The injector cannot find the referenced ConfigMap.Solution:

Pods should start normally even without ConfigMaps (using schema defaults). If pods are failing, the issue is likely elsewhere.

Check ConfigMap exists in the same namespace:

kubectl get configmap sentry-options-myrepo -n my-namespace

Check injector logs for errors
Temporarily remove annotations to verify it’s the cause:

# annotations:
#   options.sentry.io/inject: 'true'
#   options.sentry.io/namespace: myrepo

Getting help

If you’re still stuck:

Check the error message carefully - It usually indicates exactly what’s wrong
Search recent issues in sentry-options repo
Ask in #dev-infra Slack channel with:
- Full error message
- Relevant schema/values files
- What you’ve already tried
File an issue at https://github.com/getsentry/sentry-options/issues

Get Started

Integration Guide

Core Concepts

Guides

Validation errors

Schema evolution errors

Runtime errors

Local development issues

CI/CD issues

Getting help

Build docs developers (and LLMs) love

Get Started

Integration Guide

Core Concepts

Guides

​Validation errors

​Schema evolution errors

​Runtime errors

​Local development issues

​CI/CD issues

​Getting help

Build docs developers (and LLMs) love

Validation errors

Schema evolution errors

Runtime errors

Local development issues

CI/CD issues

Getting help