cube-js/cube · error · UserError

Required import for ${fileName} is not found

Error message

Required import for ${fileName} is not found

What it means

When a non-module data model file uses a relative import (`./file.js`), resolveModuleFile looks the file up in the list of files being compiled. If no file with that name is in the compile set, it throws this UserError. This catches imports pointing to files that don't exist or weren't included in compilation.

Source

Thrown at packages/cubejs-schema-compiler/src/compiler/DataSchemaCompiler.ts:989

    return clone;
  }

  private standaloneCompileContextProxy() {
    return new Proxy({}, {
      get: () => {
        throw new UserError('COMPILE_CONTEXT can\'t be used unless contextToAppId is defined. Please see https://cube.dev/docs/config#options-reference-context-to-app-id.');
      }
    });
  }

  private resolveModuleFile(currentFile: FileContent, modulePath: string, toCompile: FileContent[], errorsReport: ErrorReporter) {
    const localImport = modulePath.match(/^\.\/(.*)$/);

    if (!currentFile.isModule && localImport) {
      const fileName = localImport[1].match(/^.*\.js$/) ? localImport[1] : `${localImport[1]}.js`;
      const foundFile = toCompile.find((f) => f.fileName === fileName);
      if (!foundFile) {
        throw new UserError(`Required import for ${fileName} is not found`);
      }
      return foundFile;
    }

    const nodeModulesPath = path.resolve('node_modules');
    let absPath = currentFile.isModule ?
      path.resolve('node_modules', path.dirname(currentFile.fileName), modulePath) :
      path.resolve('node_modules', modulePath);

    if (!absPath.startsWith(nodeModulesPath)) {
      if (this.allowNodeRequire) {
        return null;
      }
      throw new UserError(`'${modulePath}' restricted`);
    }
    const packagePath = absPath.replace(nodeModulesPath, '').split('/').filter(s => !!s)[0];
    if (!packagePath) {
      if (this.allowNodeRequire) {

View on GitHub (pinned to 7d981676b3)

Solutions

1. Fix the relative path/extension so it exactly matches an existing file inside the schema directory.
2. Move shared JS modules into the schema folder (schemaPath) so the compiler includes them.
3. If using the repository/repositoryFactory API, ensure fileRepository includes the imported file.
4. For real npm dependencies, import by package name instead of a relative path (node_modules branch handles that).

Example fix

// before (schema/index.js)
const helpers = require('./utils/helpers.js'); // file lives at project root
// after
const helpers = require('./helpers.js'); // copy helpers.js next to schema files, or use an npm package

const fs = require('fs');
const target = `schema/${fileName}`;
if (!fs.existsSync(target)) {
  throw new Error(`Schema import target missing: ${target}`);
}

try { await compiler.compile(); } catch (e) { if (/Required import for .* is not found/.test(e.message)) { console.error('Fix relative path or move file into schemaPath:', e.message); } throw e; }

When it happens

Trigger: A schema JS file does `const utils = require('./helpers.js')` (or the transpiled equivalent) but `helpers.js` is missing, has a different name/extension, or lives outside the schema directory that Cube watches, so it's not in toCompile.

Common situations: Importing shared JS helpers that live outside the configured schemaPath; wrong relative path after moving files; extension mismatch (file is .ts or .mjs while import says .js); files excluded from the repository that the compiler scans (e.g. .gitignore'd helpers, Docker image missing the file).

Related errors

• Expected one parameter but nothing found
• Expected only 2 parameters for timestamp filter but got: ${t
• Unsupported timestamp precision: ${this.query.timestampPreci
• Unsupported measure type replacement for ${sourceMeasure}: $
• Unsupported additional filters for measure ${sourceMeasure}

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