louislam/dockge · info · ValidationError

Stack name must be a string

Error message

Stack name must be a string

What it means

The getStack agent socket handler validates stackName with typeof(stackName) !== 'string' and throws ValidationError('Stack name must be a string') otherwise, before Stack.getStack resolves the stack. It prevents malformed requests from reaching the stack lookup.

Source

Thrown at backend/agent-socket-handlers/docker-socket-handler.ts:75

                server.sendStackList();
                callbackResult({
                    ok: true,
                    msg: "Deleted",
                    msgi18n: true,
                }, callback);

            } catch (e) {
                callbackError(e, callback);
            }
        });

        agentSocket.on("getStack", async (stackName : unknown, callback) => {
            try {
                checkLogin(socket);

                if (typeof(stackName) !== "string") {
                    throw new ValidationError("Stack name must be a string");
                }

                const stack = await Stack.getStack(server, stackName);

                if (stack.isManagedByDockge) {
                    stack.joinCombinedTerminal(socket);
                }

                callbackResult({
                    ok: true,
                    stack: await stack.toJSON(socket.endpoint),
                }, callback);
            } catch (e) {
                callbackError(e, callback);
            }
        });

        // requestStackList

View on GitHub (pinned to f809ae192b)

Solutions

1. Emit getStack with a plain string stack name
2. Ensure the stack name variable is defined/loaded before emitting
3. Fix callers that pass an object instead of the name field

Example fix

// before
agentSocket.emit("getStack", stackObj, cb);
// after
agentSocket.emit("getStack", stackObj.name, cb);

if (typeof stackName !== "string") {
    throw new Error("getStack requires a string stack name");
}

function isStackName(v: unknown): v is string {
    return typeof v === "string" && v.length > 0;
}

agentSocket.emit("getStack", stackName, (res) => {
    if (!res.ok && res.msg === "Stack name must be a string") {
        // correct the payload type and retry
    }
});

When it happens

Trigger: Client emits 'getStack' with a non-string first argument: undefined (argument omitted), a number, an object like {name:...}, or null.

Common situations: Calling getStack before the stack list loads so the name variable is undefined; passing a numeric stack id; frontend state where the selected stack is an object rather than its name.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Name must be a string
• Stack name and service name must be strings
• Invalid stackName or serviceName
• isAdd must be a boolean
• Command must be a string.

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