BabylonJS/Babylon.js · error

uniqueId must be a number.

Error message

uniqueId must be a number.

What it means

Thrown by the inspector's make-query CLI command when the uniqueId argument cannot be parsed as a base-10 integer (parseInt returns NaN). The command requires a numeric entity uniqueId to look up an entity in a registered query collection. It is an argument-validation guard before any entity lookup happens.

Source

Thrown at packages/dev/inspector-v2/src/services/cli/entityQueryService.ts:125

                throw new Error("No active scene.");
            }

            const entities = collection.getEntities(scene);
            if (!entities) {
                return JSON.stringify([], null, 2);
            }

            if (!args.uniqueId) {
                return JSON.stringify(
                    entities.map((e) => collection.getSummary(e)),
                    null,
                    2
                );
            }

            const id = parseInt(args.uniqueId, 10);
            if (isNaN(id)) {
                throw new Error("uniqueId must be a number.");
            }

            const entity = entities.find((e) => collection.getUniqueId(e) === id);
            if (!entity) {
                throw new Error(`No ${collection.id.replace("query-", "")} found with uniqueId ${id}.`);
            }

            return JSON.stringify(collection.serialize ? collection.serialize(entity) : collection.getSummary(entity), null, 2);
        },
    };
}

/**
 * Service that registers CLI commands for querying scene entities by uniqueId.
 * When uniqueId is omitted, returns a summary list of all entities of that type.
 */
export const EntityQueryServiceDefinition: ServiceDefinition<[], [IBridgeCommandRegistry, ISceneContext]> = {
    friendlyName: "Entity Query Service",

View on GitHub (pinned to 0592b347b8)

Solutions

1. Pass the numeric uniqueId of the entity, e.g. execute make-query with uniqueId "42".
2. Verify the id with a list/query command (the collection's summary output includes uniqueIds) before invoking make-query.
3. Strip non-numeric prefixes from the id before passing it; note parseInt(…,10) only accepts decimal digits (optionally signed).

Example fix

// before
execute("make-query", { uniqueId: "mesh-42" });
// after
execute("make-query", { uniqueId: "42" });

const parsed = Number.parseInt(args.uniqueId, 10);
if (Number.isNaN(parsed)) throw new TypeError(`uniqueId must be a decimal number, got: ${JSON.stringify(args.uniqueId)}`);

function isValidUniqueId(v: unknown): v is string { return typeof v === "string" && /^-?\d+$/.test(v.trim()); }

try {
  await makeQuery(args);
} catch (e) {
  if (e instanceof Error && e.message === "uniqueId must be a number.") {
    return listEntities(); // guide user to valid ids
  }
  throw e;
}

When it happens

Trigger: Calling the 'make-query' CLI command with a missing, empty, or non-numeric args.uniqueId (e.g. "abc", "", "12.5.3", or whitespace).

Common situations: Copy-pasting an entity name instead of its uniqueId; an AI/CLI agent hallucinating an id; passing a hex id like "0x1F" that parseInt(…,10) rejects; forgetting the argument entirely in scripted invocations.

Related errors

• cameraUniqueId must be a number.
• precision must be a finite number greater than 0.
• width must be a finite positive integer.
• Unknown variant "${variant}". Use: compiled, raw, or beforeM
• Sample2DRgbaToRef: widthPx and heightPx must be positive.

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/77fb817399ec35f3. Report an issue: GitHub.