Loki Error Guide: 'flag provided but not defined'

Overview

Loki parses its command-line flags before it does anything else, and it exits immediately if it is handed a flag the running binary does not define:

flag provided but not defined: -boltdb.shipper.compactor.working-directory

There is no crash loop of retries — the process fails fast at argument parsing and never reaches config loading. This almost always means the flag was renamed or removed in the Loki version you are now running, while your manifest, systemd unit, or Helm values still pass the old name. Flags are the most version-sensitive surface in Loki: many settings that once lived on the command line have been moved into the config file, and the exact flag names shift between releases. The fix is to align the arguments with what loki -help reports for the image you are actually running.

Symptoms

Loki exits instantly at startup with flag provided but not defined: and the offending flag name.
The failure predates any config parsing — you never see a failed parsing config or Loki started line.
The same arguments worked on a previous Loki image and broke after an image bump.
A Helm or Kustomize extraArgs/args list carries a flag the new binary no longer knows.
loki -help does not list the flag your manifest passes.

Common Root Causes

Flag renamed or removed across versions — a CLI flag like -boltdb.shipper.compactor.working-directory was renamed or dropped, but the manifest still passes it.
Typo in the flag name — a mistyped or mis-hyphenated flag that the parser cannot match to any defined flag.
Setting is now config-file only — the option was migrated out of CLI flags entirely and must be expressed in the YAML config instead.
Version mismatch between manifest and image — the args target one Loki version while the container runs a different one.
Copied args from another distribution — flags borrowed from a different component or an older tutorial that never applied to this binary.

How to diagnose

List the flags the running binary actually defines — this is the definitive source of truth for your version:
```
loki -help 2>&1 | grep -i compactor
```

Read the startup logs to capture the exact rejected flag:

kubectl logs -l app=loki --tail=15 | grep 'flag provided but not defined'

Verify config loading is fine once the flag is removed, so you know the flag was the only blocker:
```
loki -config.file=/etc/loki/config.yaml -verify-config
```
Express the setting in config rather than as a flag, since many options are now config-only:
```
compactor:
  working_directory: /loki/compactor
```
Confirm the image version matches the arguments you are passing:
```
loki -version
```

Fixes

Run loki -help and remove or rename the flag to match what the current binary defines. This immediately shows whether the flag still exists and under what name:

loki -help 2>&1 | grep -- '-compactor'
# then drop or rename the offending arg in your manifest

Move the setting into the config file when the flag was migrated out of the CLI. Most storage and compactor options now live in YAML, not on the command line:

# replaces -boltdb.shipper.compactor.working-directory
compactor:
  working_directory: /loki/compactor
storage_config:
  boltdb_shipper:
    active_index_directory: /loki/boltdb-shipper-active
    cache_location: /loki/boltdb-shipper-cache

Trim the args down to what the version supports, keeping only the flags Loki still defines and letting the config file carry the rest:

args:
  - -config.file=/etc/loki/config.yaml
  - -config.expand-env=true

Pin and align the image version with the args so a manifest and binary never drift. Match the container tag to the flags and config you have validated:

containers:
  - name: loki
    image: grafana/loki:3.4.2
    args:
      - -config.file=/etc/loki/config.yaml

Fix a simple typo when the flag does still exist — correct the spelling or hyphenation to the exact name from -help:

# wrong:  -config.expand.env=true
# right:  -config.expand-env=true
loki -config.file=/etc/loki/config.yaml -config.expand-env=true

What to watch out for

loki -help is version-specific — always run it from the same image tag you deploy, not a locally installed older binary.
Removing a flag is not enough if the setting still matters; move it into the config file so you do not silently lose the behaviour.
Flag parsing happens before config loading, so this error masks nothing else — fix the args first, then re-check the config with -verify-config.
Pin image tags rather than using latest; an unpinned bump can remove a flag and break startup with no code change on your side.
Do not copy flags from another Loki component or an old tutorial; the single-binary, distributed, and per-target flag sets differ and drift between releases.

Loki Error Guide: ‘no org id’ — another startup failure that surfaces after a version or config change.
Loki Error Guide: ‘empty ring’ — a ring startup error you may hit next once the flags are fixed.
Loki Error Guide: ‘context deadline exceeded’ — the timeout error that appears once Loki starts but cannot reach a dependency.

Loki Error Guide: 'flag provided but not defined' — Fix Renamed and Removed CLI Flags

Fixing errors like this? Get 500 free DevOps AI prompts