Loki Error Guide: 'invalid schema config'

Overview

Loki validates schema_config at startup and refuses to run when an index store is paired with an incompatible index period or schema version. The most common form calls out the 24h requirement directly:

invalid schema config: boltdb-shipper works best with 24h periodic index config

You will see closely related variants for TSDB and for unknown versions:

schema config for tsdb requires 24h index period
unrecognized schema version

Both boltdb-shipper and tsdb index stores are built around daily index tables, so their schema_config entries must set index.period: 24h. Loki also refuses to run when the schema version is too old for the chosen store (TSDB needs v13), when the store/object_store pair is inconsistent, or when two schema entries overlap on their from dates. Because schema changes are historical and permanent, the fix is almost always to add a new, future-dated entry rather than edit an existing one.

Symptoms

Loki exits at startup with invalid schema config naming the 24h index period requirement.
Switching to TSDB surfaces schema config for tsdb requires 24h index period.
A hand-edited or copied config reports unrecognized schema version.
Queries for older data break after someone edited a historical schema entry in place.
The config passes a YAML linter but fails Loki’s own semantic validation.

Common Root Causes

Index period not 24h — a boltdb-shipper or tsdb schema entry sets index.period to something other than 24h, which those stores reject.
Store / object_store mismatch — the store (index) and object_store (chunks) values are inconsistent with the schema, e.g. tsdb index with a missing or wrong object store.
Schema version too old for the store — using v11 or v12 where TSDB requires v13, so validation fails.
Overlapping from dates — two schema entries whose date ranges overlap, leaving Loki unable to decide which applies.
Historical schema edited in place — changing an existing entry’s from, store, or period orphans previously written data and can invalidate the config.

How to diagnose

Validate the schema offline so you see the exact rejection without crash-looping the cluster:
```
loki -config.file=/etc/loki/config.yaml -verify-config
```
Capture the precise message from the logs, since 24h-period and version errors have different fixes:
```
kubectl logs -l app=loki --tail=30 | grep -i 'schema config'
```

Review the current schema_config and confirm each entry’s period, store, and version line up:

schema_config:
  configs:
    - from: 2024-01-01
      store: tsdb
      object_store: s3
      schema: v13
      index:
        prefix: index_
        period: 24h

Check for overlapping or out-of-order from dates across entries, which Loki treats as ambiguous:
```
grep -n 'from:' /etc/loki/config.yaml
```
Confirm the binary supports the schema version you are targeting before committing to v13 + tsdb:
```
loki -version
```

Fixes

Set the index period to 24h on every boltdb-shipper and tsdb schema entry — this is the requirement the error names directly:

schema_config:
  configs:
    - from: 2024-01-01
      store: boltdb-shipper
      object_store: s3
      schema: v12
      index:
        prefix: index_
        period: 24h

Use the current store/schema combination for new setups: TSDB index, an object store for chunks, and schema v13. This is the recommended modern configuration:

schema_config:
  configs:
    - from: 2025-06-01
      store: tsdb
      object_store: s3
      schema: v13
      index:
        prefix: index_
        period: 24h

Add a new schema entry with a future from date instead of editing the old one. Loki applies each entry to data written on or after its from, so migrations are additive:

schema_config:
  configs:
    - from: 2024-01-01      # existing data — leave untouched
      store: boltdb-shipper
      object_store: s3
      schema: v12
      index: { prefix: index_, period: 24h }
    - from: 2025-07-15      # future date — new writes use TSDB v13
      store: tsdb
      object_store: s3
      schema: v13
      index: { prefix: tsdb_index_, period: 24h }

Align store and object_store with matching storage_config blocks so the index and chunk backends actually exist for the version you name:

storage_config:
  tsdb_shipper:
    active_index_directory: /loki/tsdb-index
    cache_location: /loki/tsdb-cache
  aws:
    s3: s3://region/loki-chunks

Never change a historical schema in place — set the new entry’s from to a date strictly after your last one, so old tables keep resolving under their original schema.

What to watch out for

boltdb-shipper and tsdb both mandate a 24h index period; any other value fails validation, so do not copy a legacy non-shipper period.
Schema entries are permanent history — editing an existing from, store, or period can make already-written data unqueryable.
Always give a migration entry a from date in the future (or at least after the last entry) to avoid overlap errors.
TSDB requires schema v13; pairing it with v11/v12 triggers unrecognized schema version or a validation failure.
Keep object_store consistent with a real storage_config backend — a schema that names s3 needs a configured S3 block, or chunks have nowhere to go.

Loki Error Guide: ‘the query time range exceeds the limit’ — query bounds that interact with how index periods shard your data.
Loki Error Guide: ‘too many chunks to fetch’ — read-path pressure often traced back to index and schema layout.
Loki Error Guide: ‘failed to flush chunks’ — the write-path failure that follows a store/schema mismatch.

Loki Error Guide: 'invalid schema config' — Set 24h Index Periods and Add New Schemas Safely

Fixing errors like this? Get 500 free DevOps AI prompts