What causes "env-backed environment variables are read-only" in conductor-oss/conductor?

If you need writable environment variables, switch conductor.environment.type to a writable backend (e.g. a DB-backed DAO) instead of the default 'env'.

conductor-oss/conductor · warning · UnsupportedOperationException

env-backed environment variables are read-only

Error message

env-backed environment variables are read-only

What it means

Thrown by EnvVariableEnvironmentDAO.setEnvVariable. This DAO backs the EnvironmentDAO with read-only process environment variables (filtered by the CONDUCTOR_ENV_ prefix). Because the OS process environment cannot be mutated at runtime, writes are permanently rejected. It is the default impl (matchIfMissing=true when conductor.environment.type is unset or 'env').

Source

Thrown at core/src/main/java/com/netflix/conductor/core/env/EnvVariableEnvironmentDAO.java:47

        havingValue = "env",
        matchIfMissing = true)
public class EnvVariableEnvironmentDAO implements EnvironmentDAO {

    private final String prefix;

    public EnvVariableEnvironmentDAO(
            @Value("${conductor.environment.env.prefix:CONDUCTOR_ENV_}") String prefix) {
        this.prefix = prefix;
    }

    @Override
    public String getEnvVariable(String key) {
        return EnvVarLookup.lookup(prefix, key);
    }

    @Override
    public void setEnvVariable(String key, String value) {
        throw new UnsupportedOperationException("env-backed environment variables are read-only");
    }

    @Override
    public void delete(String key) {
        throw new UnsupportedOperationException("env-backed environment variables are read-only");
    }

    @Override
    public List<EnvironmentVariable> getAll() {
        List<EnvironmentVariable> result = new ArrayList<>();
        for (Map.Entry<String, String> e : EnvVarLookup.allWithPrefix(prefix).entrySet()) {
            result.add(EnvironmentVariable.of(e.getKey(), e.getValue()));
        }
        return result;
    }
}

View on GitHub (pinned to cf7c3e4a8a)

Solutions

If you need writable environment variables, switch conductor.environment.type to a writable backend (e.g. a DB-backed DAO) instead of the default 'env'.
Do not call setEnvVariable against the env-backed DAO; provision variables in the process environment (CONDUCTOR_ENV_* keys) before startup.
Guard API/UI code to hide the write action when the DAO is the read-only variant.

Defensive patterns

Strategy: validation

Validate before calling

// Only call set if the DAO is writable
if (!isReadOnlyEnvDao(environmentDAO)) {
    environmentDAO.setEnvVariable(key, value);
}

Try / catch

try {
    environmentDAO.setEnvVariable(key, value);
} catch (UnsupportedOperationException e) {
    // read-only env-backed DAO -> provision via process env instead
}

Prevention

Know which EnvironmentDAO impl is active before issuing writes.
Provision CONDUCTOR_ENV_* variables in the process environment rather than via runtime writes.
Switch to a writable DAO if runtime writes are required.

When it happens

Trigger: Any code path that calls environmentDAO.setEnvVariable(key, value) while the env-backed DAO is active — e.g. an API endpoint or SDK call that tries to create/update an environment variable.

Common situations: A client tries to set an environment variable through the API not realizing the server is using the env-backed (read-only) DAO. A test that exercises setEnvVariable against the default profile. Confusion between Conductor 'environment variables' (runtime config values) and OS env vars.

Related errors

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/21afd68b0fc373b1. Report an issue: GitHub.