> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.ampdb.io/api/mcp` to find what you need. # Configuration `ampd` reads its settings from a configuration file, written in [TOML](https://toml.io), and from environment variables. Every setting has a default except the [metadata database](/running-amp/metadata-database)'s URL, which [solo mode](/running-amp/solo-mode) provides itself. So in solo mode, you only need a configuration to change something; in [distributed mode](/running-amp/distributed-mode), every service needs one. This page explains how the configuration works. Every setting is in the [Configuration Reference](/running-amp/configuration-reference), except the metadata database's, which are in [Metadata Database](/running-amp/metadata-database#settings). ## The configuration file Give `ampd` the file with `--config`, before the command, or the `AMP_CONFIG` environment variable: ```bash ampd --config /etc/amp/config.toml server ``` Every command except `solo` requires it. Solo mode reads `config.toml` in its [state directory](/running-amp/solo-mode#the-amp-directory) when you don't give it one. A configuration for a deployment usually sets the metadata database and where Amp stores its files, and leaves the rest to the defaults: ```toml [config.toml] # Where Amp stores datasets, providers, and manifests data_dir = "s3://acme-amp/data" providers_dir = "s3://acme-amp/providers" manifests_dir = "s3://acme-amp/manifests" [metadb] url = "postgresql://amp:amp@db.internal:5432/amp" [server] max_mem_mb = 16384 [worker.metadb] pool_size = 20 ``` For a file with every setting and its default, start from Amp's [sample configuration](https://github.com/edgeandnode/amp/blob/f27102fd59608258dc58a6dbbaac880f124364ae/docs/config.sample.toml). ### Sections | Section | What it configures | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Top level: `data_dir`, `providers_dir`, `manifests_dir` | Where Amp stores datasets' files, providers, and manifests. See [Storage](/running-amp/storage). | | `[metadb]` | The connection to the [metadata database](/running-amp/metadata-database). | | `[writer]` | The Parquet files workers write, and the [metadata cache](/running-amp/storage/metadata-caching). | | `[writer.compactor]` | How workers [compact](/running-amp/storage/compaction) files. | | `[location_membership]` | The [cache of each table's files](/running-amp/storage/metadata-caching#file-lists). | | `[logging]` | The [logs](/running-amp/telemetry#logs)' format. | | `[server]`, `[server.metadb]` | The [query server](/running-amp/query-server). | | `[worker]`, `[worker.metadb]`, `[worker.events]` | The [worker](/running-amp/worker), and its [events](/running-amp/worker-events). | | `[controller]`, `[controller.metadb]` | The [controller](/running-amp/controller). | ### Values * **Paths** that are relative are relative to the configuration file's directory, not to the directory you run `ampd` in. `data_dir = "data"` in `/etc/amp/config.toml` is `/etc/amp/data`. Without these settings, a `--config` path that's relative and has a directory in it, like `conf/config.toml`, fails with `failed to canonicalize path`, because Amp applies the directory twice. Pass an absolute path, run `ampd` from the file's directory, or set the three directories. * **Durations** are in seconds. Some accept decimals, like `min_interval = 0.5`: the reference gives each setting's type. * **Sizes** are in MiB for settings that end with `_mb`, and in bytes otherwise, like `max_eager_bytes = 102400`. * **Addresses** are an IP address and a port, like `"0.0.0.0:1602"`. `ampd` checks the values it reads when it starts, and doesn't start with a wrong one. The error names the file and the setting: ``` Exiting with error: Failed to load config | Caused by: Config parse error at /etc/amp/config.toml -> Failed to load configuration file -> invalid type: found string "lots", expected usize for key "default.max_mem_mb.server" in /etc/amp/config.toml TOML file ``` :::warning `ampd` ignores settings it doesn't know, without an error. A misspelled setting, like `flight_adr`, keeps its default: check the names against the [reference](/running-amp/configuration-reference). ::: ## Environment variables Any setting can be set in an environment variable instead: its name is `AMP_CONFIG_`, then the setting's path in uppercase, with `__` (two underscores) between a section and what's in it. | Setting | Environment variable | | ----------------------------------- | ------------------------------------------------- | | `data_dir` | `AMP_CONFIG_DATA_DIR` | | `metadb.url` | `AMP_CONFIG_METADB__URL` | | `server.flight_addr` | `AMP_CONFIG_SERVER__FLIGHT_ADDR` | | `worker.metadb.pool_size` | `AMP_CONFIG_WORKER__METADB__POOL_SIZE` | | `worker.events.kafka.sasl_password` | `AMP_CONFIG_WORKER__EVENTS__KAFKA__SASL_PASSWORD` | The reference gives each setting's variable. Write lists in brackets, like in TOML: `AMP_CONFIG_SERVER__SPILL_LOCATION='["/var/tmp/amp-spill"]'`. An environment variable wins over the file, which makes it the place for: * **Secrets**, like the database's password, so they stay out of the file. * **What differs between machines** that share a file, like a port or a memory limit. For example, the query server logs its memory limit when it starts: :::terminal ```bash AMP_CONFIG_SERVER__MAX_MEM_MB=2048 ampd --config config.toml server ``` ``` 2026-10-30T16:52:07.526031Z INFO ampd::server_cmd: Memory limit is 2048 MB ``` ::: ## Per-service settings Each service reads the shared settings, from the top level and the shared sections, and its own section: | Command | Reads | | ----------------- | ------------------------------------------------------------------------------- | | `ampd controller` | The shared settings, `[controller]`, and `[controller.metadb]` | | `ampd server` | The shared settings, `[server]`, and `[server.metadb]` | | `ampd worker` | The shared settings, `[worker]`, `[worker.metadb]`, and `[worker.events]` | | `ampd migrate` | The shared settings | | `ampd solo` | Every section, except the `[.metadb]` ones: it uses `[metadb]` for all | Since each service only reads its own section, every service can share one file, and a mistake in `[worker]` doesn't stop a query server. ## Global defaults The query server and workers both run SQL, so both have the same five settings for it: `max_mem_mb`, `query_max_mem_mb`, `spill_location`, `metadata_fetch_concurrency`, and `microbatch_max_interval`. Set one at the top level to apply it to both, and in a section to set it for that service only: ```toml [config.toml] # For the query server and workers microbatch_max_interval = 50000 [server] # For the query server only: workers keep 50000 microbatch_max_interval = 250000 ``` A global default only fills the sections that don't set the setting. So a section's value always wins, even when the global default comes from an environment variable, like `AMP_CONFIG_MICROBATCH_MAX_INTERVAL`. ## Precedence When a setting has several values, `ampd` uses the first of: 1. The setting's environment variable, like `AMP_CONFIG_SERVER__MAX_MEM_MB`. 2. The setting in the file. 3. A fallback, for the settings that have one: a [global default](/running-amp/configuration#global-defaults), from an environment variable or the file, or the value under a [deprecated name](/running-amp/configuration#deprecated-settings). 4. Its default. The metadata database's settings work the same way, with a step for each service's own pool: see [Per-service pools](/running-amp/metadata-database#per-service-pools). ## Deprecated settings These settings moved. Their old names still work, in the file or in an environment variable, like `AMP_CONFIG_FLIGHT_ADDR`, and a value under the new name wins, even when the old name is in an environment variable and the new one in the file. Use the new names: the old ones are deprecated. v0.0.42 doesn't warn when it reads an old name, so check your files and environment for them. | Old name | New name | | --------------------- | ---------------------------- | | `dataset_defs_dir` | `manifests_dir` | | `flight_addr` | `server.flight_addr` | | `keep_alive_interval` | `server.keep_alive_interval` | | `admin_api_addr` | `controller.admin_api_addr` | | `worker_health_addr` | `worker.health_addr` | | `poll_interval_secs` | `worker.poll_interval_secs` | | `[worker_events]` | `[worker.events]` | | `[metadata_db]` | `[metadb]` | | `metadata_db_url` | `metadb.url` | ## Troubleshooting ### `Missing required metadata database configuration` ``` Exiting with error: Missing required metadata database configuration. Provide metadb.url via TOML config file or AMP_CONFIG_METADATA_DB__URL environment variable ``` The service has no database URL, or the `[metadb]` section has a wrong value, like a `pool_size` that isn't a number. Set `metadb.url`, or `AMP_CONFIG_METADB__URL` (the message's `AMP_CONFIG_METADATA_DB__URL` is its deprecated name), and check the section against [the settings](/running-amp/metadata-database#settings). ### `failed to canonicalize path` ``` Exiting with error: Failed to load config | Caused by: Invalid object store URL at /etc/amp/config.toml -> invalid filesystem path: /etc/amp/data -> failed to canonicalize path `/etc/amp/data`: No such file or directory (os error 2) ``` A storage directory doesn't exist. Outside solo mode, `ampd` doesn't create them: create it, or fix the path. ### A setting has no effect Check its name against the [reference](/running-amp/configuration-reference): `ampd` ignores the ones it doesn't know. Then check that no environment variable overrides it (`env | grep AMP_CONFIG_`), and that you restarted the service: `ampd` only reads its configuration when it starts.