louislam/dockge · error · ValidationError

Invalid .env format

Error message

Invalid .env format

What it means

After parsing the compose YAML, Stack.validate() checks composeENV: docker-compose rejects a single-line .env that has no '=' (it triggers 'setenv: The parameter is incorrect'). A non-empty single line lacking '=' therefore throws this ValidationError to fail fast with a clearer message.

Source

Thrown at backend/stack.ts:129

        return this._status;
    }

    validate() {
        // Check name, allows [a-z][0-9] _ - only
        if (!this.name.match(/^[a-z0-9_-]+$/)) {
            throw new ValidationError("Stack name can only contain [a-z][0-9] _ - only");
        }

        // Check YAML format
        yaml.parse(this.composeYAML);

        let lines = this.composeENV.split("\n");

        // Check if the .env is able to pass docker-compose
        // Prevent "setenv: The parameter is incorrect"
        // It only happens when there is one line and it doesn't contain "="
        if (lines.length === 1 && !lines[0].includes("=") && lines[0].length > 0) {
            throw new ValidationError("Invalid .env format");
        }
    }

    get composeYAML() : string {
        if (this._composeYAML === undefined) {
            try {
                this._composeYAML = fs.readFileSync(path.join(this.path, this._composeFileName), "utf-8");
            } catch (e) {
                this._composeYAML = "";
            }
        }
        return this._composeYAML;
    }

    get composeENV() : string {
        if (this._composeENV === undefined) {
            try {
                this._composeENV = fs.readFileSync(path.join(this.path, ".env"), "utf-8");

View on GitHub (pinned to f809ae192b)

Solutions

1. Format the .env line as KEY=value, e.g. 'DEBUG=true'.
2. Remove the stray line if no env var is needed (empty string is allowed).
3. Add a second line or trailing newline only if it is a valid KEY=value pair; the validation only rejects the single-line no-'=' case.

Example fix

// before
stack.composeENV = 'DEBUG';
stack.save();
// after
stack.composeENV = 'DEBUG=true';
stack.save();

function isValidEnvContent(env) {
    if (typeof env !== 'string') return false;
    const lines = env.split('\n');
    return !(lines.length === 1 && lines[0].length > 0 && !lines[0].includes('='));
}

try {
    stack.save();
} catch (e) {
    if (e.message.includes('.env')) {
        e.message = 'Each .env line must be KEY=value';
        throw e;
    }
}

When it happens

Trigger: Saving a stack where composeENV is exactly one non-empty line that contains no '=', e.g. 'DEBUG' or 'just some text'. Multi-line values or lines with '=' pass this check.

Common situations: Pasting a bare variable name without its value; trailing newline removed so lines.length === 1; writing a comment or note into the .env editor.

Related errors

• Stack name can only contain [a-z][0-9] _ - only
• Name must be a string
• Stack name must be a string
• Stack name and service name must be strings
• Invalid stackName or serviceName

AI-assisted analysis of louislam/dockge@f809ae192b (2026-08-31). Data as JSON: /api/errors/a30bfa57af0c3cb5. Report an issue: GitHub.