cube-js/cube · error · UserError

Unsupported Python multiple children node: ${node.constructo

Error message

Unsupported Python multiple children node: ${node.constructor.name}: ${node.getText()}

What it means

This UserError is thrown by PythonParser.transpileToJs() during Python-to-JavaScript transpilation of a Cube data model. The visitor's singleNodeReturn() helper expects a parse-tree node to reduce to exactly one child; when an AST node (typically an AtomContext with unsupported content like a parenthesized expression or list) produces zero or multiple children, the transpiler refuses to guess a mapping and throws, naming the ANTLR context class and source text.

Source

Thrown at packages/cubejs-schema-compiler/src/parser/PythonParser.ts:136

    const parser = new Python3Parser(
      commonTokenStream
    );
    parser.buildParseTrees = true;
    parser.removeErrorListeners();
    parser.addErrorListener(new ExprErrorListener());

    return parser.file_input();
  }

  public transpileToJs(): t.Program {
    return this.ast.accept(nodeVisitor<any>({
      visitNode: (node, children) => {
        const singleNodeReturn = () => {
          if (children.length === 1) {
            return children[0];
          } else {
            throw new UserError(`Unsupported Python multiple children node: ${node.constructor.name}: ${node.getText()}`);
          }
        };

        if (node instanceof File_inputContext) {
          return t.program(children);
        } else if (node instanceof Expr_stmtContext) {
          if (children.length === 1) {
            return t.expressionStatement(children[0]);
          } else {
            throw new UserError(`Unsupported Python multiple children node: ${node.constructor.name}: ${node.getText()}`);
          }
        } else if (
          node instanceof Double_string_template_atomContext ||
          node instanceof Single_string_template_atomContext
        ) {
          if ((node.test() || node.star_expr()) && children.length === 1) {
            return children[0];
          }

View on GitHub (pinned to 7d981676b3)

Solutions

Rewrite the Python model to use only the supported subset: plain literals, identifiers, simple function calls, attribute access, and lambdas
Replace container literals (tuples/lists/dicts) with multiple assignments or simple single expressions
Check the node class name and text in the message to find the offending line, and simplify that exact expression
If a supported construct is being rejected, inspect packages/cubejs-schema-compiler/src/parser/PythonParser.ts visitNode branches and file an issue / add a mapping for the missing context

Example fix

// before (cubes.py)
dims = ['a', 'b']
cube(name=dims[0])
// after
name = 'a'
cube(name=name)

Defensive patterns

Strategy: validation

Validate before calling

// Keep model Python within the supported subset before compiling
const SUPPORTED = /^[\w\s.'"(),:=*+\-]+$/;
if (!SUPPORTED.test(pySource)) throw new Error('Model uses constructs outside the supported Python subset');
if (/[[\]{}]|await |yield /.test(pySource)) throw new Error('Lists/dicts/await are not supported in data models');

Try / catch

try {
  compiler.compileJsFile(...); // parsePythonAndTranspileToJs
} catch (e) {
  if (e instanceof UserError && e.message.startsWith('Unsupported Python multiple children node')) {
    throw new Error(`Simplify this model expression: ${e.message}`);
  }
  throw e;
}

Prevention

Use only literals, identifiers, calls, attribute access and lambdas in data-model Python
Avoid container literals (lists, tuples, dicts) and slicing/indexing in cubes.py
Validate model files with python -m py_compile before starting Cube
Read the node class + text in the message to pinpoint the offending expression quickly

When it happens

Trigger: Calling parsePythonAndTranspileToJs (via transpileToJs) on Python data-model code where a node visited via singleNodeReturn() — e.g. an AtomContext not matching NAME/STRING/NUMBER — yields a children array whose length is not 1. Typical sources: Python syntax beyond the supported subset such as tuples, lists, dict literals, parenthesized expressions, or multiple statements in one expr line.

Common situations: Developers writing advanced Python in cubes.py (list/tuple/dict literals, f-strings with complex expressions, arithmetic in attribute defaults, decorators, imports) assume full Python support, but the Cube Python transpiler only supports a small expression subset; CI fails during schema compile with this message.

Related errors

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/42247e1ae6a33b01. Report an issue: GitHub.