Troubleshooting

The failures you are most likely to hit, why they happen, and how to fix them. If your problem is a genuine bug, open an issue on opentide.

Setup and paths

Could not resolve repository root / objects not found

OpenTide does not know where your content lives. Set the repo root explicitly:

export OPENTIDE_REPO_ROOT=/path/to/detection-repo
# or per-command
opentide --repo /path/to/detection-repo validate

See Installation → environment variables.

The command opentide is not found

The CLI ships as an extra. Install it:

pip install 'opentide==0.1.0'

Inside a virtualenv, confirm it is on PATH (which opentide). For MCP/agent hosts, point the host at the venv's opentide-mcp — see MCP configuration.

Generation

validate complains that schemas are missing

Validation checks objects against generated JSON Schemas. If they do not exist yet, generate them first:

opentide generate
opentide validate --strict

Run generate after cloning a repo, after upgrading the OpenTide package, and whenever schema revisions change.

Editor stopped validating YAML

Your IDE reads the generated router at .opentide/schemas/opentide.schema.json. If it is stale or missing:

opentide generate schemas

Then reload your editor's YAML/schema association.

Validation errors

unknown schema identifier / object won't load

metadata.schema must be a registered identifier such as rule::1.0. A typo (rule:1.0, rule::1, rules::1.0) means no model matches. Fix the value; the valid identifiers are threat::1.0, objective::1.0, rule::1.0. See Schema revision.

duplicate UUID

Two objects share a metadata.uuid. UUIDs must be unique across the repo — you almost certainly copy-pasted an object. Generate a fresh one:

python -c "import uuid; print(uuid.uuid4())"

unknown objective / dangling reference

A detection_model or objective.threats UUID points at an object that does not exist. This is the dangling reference anti-pattern — usually a typo or a deleted file. Fix the UUID or restore the target.

unknown status

A rule's status (or a platform block's status) is not defined in the merged deployment.toml. Use a bundled status (STAGING, PRODUCTION, …) or add your own — see Configuration → deployment statuses.

Warnings fail my build but pass locally

Warnings alone exit 0 by default and are listed in --json output under warnings. Pass --strict to fail the run with exit 1. If your pipeline uses --strict, reproduce it locally with the same flag:

opentide validate --strict

See Exit codes.

Query validation

supported: false for a platform

CrowdStrike and HarfangLab are deploy-only — they cannot validate query syntax, and OpenTide reports this honestly rather than faking a pass. This is expected behaviour, not an error. Validate queries on a supporting platform (Sentinel, Defender, Splunk, SentinelOne, Carbon Black). See Platforms.

MCP validate_query always returns valid

The MCP validate_query and run_query tools are stubs — they do not parse queries yet. Use the CLI (opentide validate query --platform …) for real syntax checks, or the MCP validation_report tool for structured object validation. See Agentic setup.

Platforms and deployment

A platform I configured is not loaded

Platforms load only when enabled in your workspace config:

# .opentide/configurations/platforms/sentinel.toml
[platform]
enabled = true

Verify with opentide info --platform sentinel. See Configuration → enabling a platform.

Deploy fails with an authentication error

Credentials are missing or wrong. OpenTide reads them from your platform TOML, typically via environment variables. Confirm the variables are set in your shell (or CI secrets) and match the keys the platform expects (opentide info --platform <name>). Never commit secrets — see Configuration → credentials.

deploy metadata seems to do nothing

opentide deploy metadata (Splunk lookup tables) currently signals intent in logs — full metadata deployment is pending. See deploy.

Still stuck?

• Re-run with debug logging: DEBUG=1 opentide validate --strict.
• Compare your object against a known-good fixture.
• Check the CLI reference for the exact flags and exit codes.