> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/gym/_mcp/server.

# Configuration Errors

These errors appear when running `gym env start` or `gym eval run --no-serve`. NeMo Gym validates configuration at startup before launching servers.

See the [Configuration reference](/reference/configuration) for complete configuration syntax and options.

***

## Startup Errors

Errors that prevent servers from starting.

### Unset Required Config Value(s)

```
nemo_gym.config_types.ConfigMissingValuesError: 1 required config value(s) are unset (still '???') after merging:
  - policy_api_key

Provide each value via a CLI override, in env.yaml, or in a config you pass via config_paths.
For example, on the command line:
  ++policy_api_key=<value>
```

**When**: One or more required variables (usually in `env.yaml`) are left unset (`???`) after all
config sources are merged. Every unset value is listed together in this single error.

**Fix**: Add the missing value to `env.yaml`:

```yaml
policy_api_key: sk-your-api-key
```

Or pass via command line:

```bash
gym env start \
    --config config.yaml \
    --model-api-key sk-your-api-key
```

### Server Reference Not Found

```
nemo_gym.config_types.ServerRefNotFoundError: In server instance 'my_agent', field 'resources_server' references resources_servers/'typo_weather', which is not defined in the merged config.
Did you mean: 'weather'?
```

**When**: A server config references another server that doesn't exist or isn't loaded. The error
names the referencing instance/field and then either suggests a similarly named server
(`Did you mean: …`) or, when nothing is close, lists the available servers of that type
(`Available resources_servers: …`).

**Common causes**:

* Typo in the server name
* Referenced server's config file not included in the `--config` flags
* Server defined in a different config file that wasn't loaded

**Fix**:

1. Check server name spelling in your config
2. Ensure all required config files are passed with `--config`:

```bash
gym env start \
    --config model.yaml \
    --config resource.yaml \
    --config agent.yaml
```

### Config Path Not Found

```
nemo_gym.config_types.ConfigPathNotFoundError: config_paths entry 'resources_servers/weather/config.yaml' was not found. Looked in:
  - /path/to/cwd/resources_servers/weather/config.yaml
  - /path/to/gym/resources_servers/weather/config.yaml
Check the path is spelled correctly and is relative to your working directory or the Gym install root.
```

**When**: A `config_paths` entry (in a config file or a `--config` flag) points at a file that doesn't
exist under any search root. The error lists every location that was searched.

**Fix**: Correct the path. A relative entry is resolved against your working directory and then the
Gym install root, so running from the repository root usually fixes it; an absolute path also works.

### Malformed `config_paths`

```
nemo_gym.config_types.MalformedConfigPathsError: 'config_paths' must be a list of paths. Got: 'resources_servers/weather/config.yaml'.
Pass each config with --config (it builds the list for you), e.g.:
  gym env start --config resources_servers/<env>/configs/<env>.yaml
```

**When**: `config_paths` is set to a scalar or mapping instead of a list of path strings.

**Fix**: Make it a YAML list, or pass each config with `--config`:

```yaml
config_paths:
  - resources_servers/weather/config.yaml
```

### No Server Instances Configured

```
nemo_gym.config_types.NoServerInstancesError: No server instances are configured, so there is nothing to run. Pass one or more configs, e.g.:
  gym env start --config resources_servers/<env>/configs/<env>.yaml --config responses_api_models/<model>/configs/<model>.yaml
```

**When**: The merged config defines no server instances — usually a wrong/empty `--config` or a
`config_paths` list that resolved to nothing.

**Fix**: Pass the configs that define your servers, or check the `config_paths` entries actually load.

Catch all of the above before launch with [`gym env validate`](/reference/cli-commands#gym-env-validate) — it
merges and validates the same config `gym env start` uses, then exits with a clean message (no traceback)
and a non-zero status on failure, so it fits in CI pre-flight checks.

***

## Validation Errors

Errors where config structure is correct but values are invalid.

### Almost-Servers Detected

```
Configuration Warnings: Almost-Servers Detected

  Almost-Server Detected: 'example_simple_agent'
  This server configuration failed validation:

- ResourcesServerInstanceConfig -> resources_servers -> example_server -> domain: 
  Input should be 'math', 'coding', 'agent', 'knowledge', 'instruction_following', 
  'long_context', 'safety', 'games', 'translation', 'e2e', 'rlhf' or 'other'
```

**When**: Config has the right structure (server type, entrypoint) but contains invalid field values.

**Common causes**:

* Invalid `domain` value for resources servers
* Invalid `license` value in dataset configs
* Missing required fields for the server type

**Fix**: Check the validation error path (for example, `resources_servers -> example_server -> domain`) and update the field with a valid value. Refer to [configuration-reference](/reference/configuration) for valid field values.

#### Bypass Strict Validation

To continue with invalid configs (invalid servers will be skipped):

```yaml
# In env.yaml
error_on_almost_servers: false
```

```bash
# Or via command line
gym env start \
    --config config.yaml \
    +error_on_almost_servers=false
```

Bypassing validation means invalid servers won't start. Use this only for debugging, not production.