louislam/dockge · error · Error

Event name must be a string

Error message

Event name must be a string

What it means

Second type check in the same `agent` event handler: `eventName` must be a string naming the agent event to forward. A non-string eventName throws 'Event name must be a string'. As with the endpoint check, the enclosing catch only logs the message server-side, so the client gets no explicit error callback.

Source

Thrown at backend/socket-handlers/agent-proxy-socket-handler.ts:21

import { log } from "../log";
import { checkLogin, DockgeSocket } from "../util-server";
import { AgentSocket } from "../../common/agent-socket";
import { ALL_ENDPOINTS } from "../../common/util-common";

export class AgentProxySocketHandler extends SocketHandler {

    create2(socket : DockgeSocket, server : DockgeServer, agentSocket : AgentSocket) {
        // Agent - proxying requests if needed
        socket.on("agent", async (endpoint : unknown, eventName : unknown, ...args : unknown[]) => {
            try {
                checkLogin(socket);

                // Check Type
                if (typeof(endpoint) !== "string") {
                    throw new Error("Endpoint must be a string: " + endpoint);
                }
                if (typeof(eventName) !== "string") {
                    throw new Error("Event name must be a string");
                }

                if (endpoint === ALL_ENDPOINTS) {      // Send to all endpoints
                    log.debug("agent", "Sending to all endpoints: " + eventName);
                    socket.instanceManager.emitToAllEndpoints(eventName, ...args);

                } else if (!endpoint || endpoint === socket.endpoint) {      // Direct connection or matching endpoint
                    log.debug("agent", "Matched endpoint: " + eventName);
                    agentSocket.call(eventName, ...args);

                } else {
                    log.debug("agent", "Proxying request to " + endpoint + " for " + eventName);
                    await socket.instanceManager.emitToEndpoint(endpoint, eventName, ...args);
                }
            } catch (e) {
                if (e instanceof Error) {
                    log.warn("agent", e.message);
                }

View on GitHub (pinned to f809ae192b)

Solutions

1. Pass eventName as a string in the second position: socket.emit('agent', endpoint, 'test', ...args)
2. Verify the argument order (endpoint, eventName, ...args) in the emitting code
3. Validate client-side: if (typeof eventName !== 'string') throw before emitting

Example fix

// before
socket.emit("agent", endpoint, { name: "test" }, data);
// after
socket.emit("agent", endpoint, "test", data);

if (typeof eventName !== "string" || !eventName) { throw new TypeError("agent() requires a string eventName as 2nd arg"); }
socket.emit("agent", endpoint, eventName, ...args);

const isEventName = (v: unknown): v is string => typeof v === "string" && v.length > 0;

// server catches and only logs; guard on the client
if (!isEventName(ev)) { console.error("agent event skipped: eventName must be a string"); return; }
socket.emit("agent", endpoint, ev, ...args);

When it happens

Trigger: Emitting socket event `agent` with a non-string second argument, e.g. socket.emit('agent', 'endpoint', 42, payload) or omitting eventName entirely (undefined).

Common situations: Off-by-one in the argument list (payload passed where eventName belongs); programmatic emitters building the args array dynamically; typos swapping endpoint/eventName order.

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

• Endpoint 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/a114d984d39ab014. Report an issue: GitHub.