Configuration Validation

Primary Commands

Local binary:

synctv config --config synctv.yaml validate

Development via Cargo:

cargo run -p synctv --bin synctv -- config --config synctv.yaml validate

This page covers configuration validation errors. If the service starts but access, authentication, media playback, or Ingress behavior is wrong, start from Troubleshooting.

Common Errors

OPAQUE Secret Is Empty

Meaning: security.opaque_server_setup_secret is not configured.

Fix:

export SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET="$(openssl rand -base64 48)"

Save this value in production. Do not regenerate it on every deployment.

Credential Key Format Is Invalid

security.credential_encryption_key must be 64 hexadecimal characters.

Generate:

openssl rand -hex 32

Wrong examples:

• Base64 strings.
• Human passwords.
• Any value whose length is not 64 hex characters.

CORS Origin Is Invalid

Correct:

server:
  cors_allowed_origins:
    - "https://app.example.com"

Wrong:

server:
  cors_allowed_origins:
    - "https://app.example.com/path"

CORS origins cannot include paths.

WebAuthn Origin Is Invalid

webauthn.rp_origin must also be an origin without path, query, or fragment.

Cluster Enabled but Redis Missing

cluster.enabled=true requires Redis.

Fix:

redis:
  url: "redis://redis:6379"

Cluster Enabled but Cluster Secret Missing

Fix:

export SYNCTV_SERVER_CLUSTER_SECRET="$(openssl rand -hex 32)"

Compose Debugging

Inspect final Compose config:

docker compose config

Inspect logs:

docker compose logs -f synctv

If Compose reports a required variable missing, production Compose expects explicit secrets.

Helm Debugging

Render manifests:

helm template synctv ./helm/synctv --values my-values.yaml

Lint:

helm lint ./helm/synctv

Inspect runtime ConfigMap:

kubectl get configmap synctv-config -n synctv -o yaml

List Secret keys:

kubectl get secret synctv-secrets -n synctv -o jsonpath='{.data}' | jq 'keys'

Do not paste Secret values into issues or chat.