Environment Reference Does Not Work as Documented

[suzuki-safie]

Bug Report: Environment Reference Does Not Work as Documented

Summary

We have experienced two unexpected behaviors in environment handling.

Issue 1: Environments are Referenced by Name Field Instead of Identifier

Expected Behavior

Environments are referenced by their identifier (the YAML object key), according to the documentation.

Actual Behavior

Environments are actually referenced by their name field (the YAML object value).

Related codes:

• In internal/storage/environments/git/store.go:98-99, the Key() method returns e.cfg.Name
• In internal/config/environments.go:93, the configuration defaults set name to the YAML key identifier
• In internal/server/environments/storage.go:217-227, the Get() method looks up environments by this key

---

Issue 2: Default Environment Cannot Be Customized When Environment Key is Unspecified

Expected Behavior (According to Documentation)

According to the documentation, when no environment is specified, the environment with default: true should be used, regardless of its identifier or name.

Actual Behavior

When no environment is specified in client initialization, environment with name "default" is used.
If no environment with name "default" exists, the server returns an error.

Related codes:

• In https://github.com/flipt-io/flipt-client-sdks/blob/fe8bf65aa563fe0bd76be164698a7e710a53a49d/flipt-client-python/flipt_client/__init__.py#L38 , the Python SDK uses "default" as default environment key
• After PR #4745, the server returns an error when a specified environment key cannot be found, rather than falling back to the default environment.

Environment

• Flipt v2.1.3
• Flipt Client SDKs for Python v1.3.1

[dosubot]

You’re correct—there’s a clear mismatch between the documentation and how Flipt currently handles environment references and default selection.

Issue 1: The server references environments by their name field, not the YAML key identifier. The code sets the name field to the YAML key, but all lookups and references use the name value, not the key itself. This means environments are not referenced by their identifier as the docs suggest, but by their name field instead (source).

Issue 2: When no environment is specified, both the Python SDK and the server use "default" as the environment key. If an environment named "default" doesn’t exist, the server returns an error (after PR #4745), rather than falling back to the environment marked with default: true as the documentation describes (source). The Python SDK simply passes "default" if no environment is set (source), and does not interpret the default: true flag.

There are currently no open issues or discussions tracking these specific discrepancies, and the implementation does not match the documented behavior (source). For now, environments must be referenced by their name field, and the default environment must be named "default" to avoid errors.

If you need to customize the default environment, ensure one of your environments is named "default". There’s no built-in fallback to the environment with default: true unless it’s also named "default".

Let me know if you need more details or want to discuss possible workarounds.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}