iflytek/astron-agent · critical · IllegalStateException

WORKFLOW_INTERNAL_API_KEY must contain a non-default value…

Error message

WORKFLOW_INTERNAL_API_KEY must contain a non-default value of at least 32 characters

What it means

WorkflowInternalApiKey.requireConfigured enforces that WORKFLOW_INTERNAL_API_KEY is a non-default value of at least MIN_LENGTH (32) characters, trimmed, without CR/LF. If the configured value is missing/too short/still the placeholder, it throws IllegalStateException at startup or first use, refusing insecure internal signing.

Solutions

Set WORKFLOW_INTERNAL_API_KEY to a cryptographically random value of at least 32 characters (e.g. openssl rand -hex 32)
Remove the placeholder/default value — generate a fresh secret per environment
Check the secret source for stray newlines (Kubernetes secret data, YAML folding)
Restart the service after updating the env so requireConfigured passes

Example fix

// before
# .env
WORKFLOW_INTERNAL_API_KEY=change-me
// after
# generate: openssl rand -hex 32
WORKFLOW_INTERNAL_API_KEY=9f2c4e...64-hex-chars...ab

Defensive patterns

Strategy: validation

Validate before calling

String k = System.getenv("WORKFLOW_INTERNAL_API_KEY"); boolean ok = k != null && k.trim().length() >= 32 && !"change-me".equals(k.trim()) && !k.contains("\n") && !k.contains("\r");

Try / catch

try { WorkflowInternalApiKey.requireConfigured(configuredValue); } catch (IllegalStateException e) { throw new IllegalStateException("Fix WORKFLOW_INTERNAL_API_KEY in the environment", e); }

Prevention

Generate a unique 32+ char random key per environment (openssl rand -hex 32)
Never commit placeholder values in deploy configs; use secret managers
Ensure secret delivery preserves the value verbatim (no added newlines)
Fail fast at startup and alert rather than serving with a default key

When it happens

Trigger: Env var WORKFLOW_INTERNAL_API_KEY unset or empty; left at the documented placeholder/default value; a short dev key (<32 chars) promoted to prod; a key accidentally containing newlines (e.g. multiline YAML secret).

Common situations: Deploying docker-compose/Helm without setting the secret; copying example config verbatim; Kubernetes secret with trailing newline embedded in value; local dev runs with sample .env.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/6c0650e47c722999. Report an issue: GitHub.

Appendix: source

Thrown at console/backend/commons/src/main/java/com/iflytek/astron/console/commons/security/WorkflowInternalApiKey.java:22

/** Shared validation and header naming for trusted calls to the core workflow service. */
public final class WorkflowInternalApiKey {

    public static final String HEADER = "X-Workflow-Internal-Key";

    private static final String PLACEHOLDER = "CHANGE_ME_WORKFLOW_INTERNAL_API_KEY";
    private static final int MIN_LENGTH = 32;

    private WorkflowInternalApiKey() {}

    /** Return a normalized credential or fail closed before issuing an internal request. */
    public static String requireConfigured(String configuredValue) {
        String apiKey = StringUtils.trimToEmpty(configuredValue);
        if (apiKey.length() < MIN_LENGTH
                || PLACEHOLDER.equals(apiKey)
                || apiKey.indexOf('\r') >= 0
                || apiKey.indexOf('\n') >= 0) {
            throw new IllegalStateException(
                    "WORKFLOW_INTERNAL_API_KEY must contain a non-default value of at least 32 characters");
        }
        return apiKey;
    }
}

View on GitHub (pinned to 5e758547a8)