Troubleshooting cloudpack init

So cloudpack init has failed at some point, and you're trying to find out why. This guide provides a set of troubleshooting tips to help you diagnose the problem.

You might also want to check out the repo guidance for best practices that can help avoid issues.

cloudpack init --check failed

If you run cloudpack init --check and it fails, it is probably due to one of two reasons:

1. Outdated generated config: There are updates to the generated config that need to be applied. You can run cloudpack init to apply the changes. If this doesn't work, you can also try running cloudpack init --reset to generate a fresh config.

2. Bundling errors: The package is not able to bundle correctly. You can try to fix the issues by following the steps below.

General troubleshooting steps

When a particular package fails to build, there are some common things which can cause this. First, we'll go through some common steps and then delve into specifics.

Run cloudpack init with --log-resolve-map

The job of init is to ensure every package in the graph bundles, and if it doesn't, to provides package overrides in cloudpack.generated.json.

In order for you to know what packages it finds, you can use the --log-resolve-map flag.

This will emit a resolve-map.json which tells you where every single package is resolved from, who depends on it, and what it depends on. It can also tell you if multiple scoped versions are found.

Check that the package bundles in isolation

Find the package failing and run cloudpack bundle in its folder. This will tell you if the package can bundle in isolation.

You can inspect the output folder logged by the command for results. You can also run with --log-bundle-info to check the {bundler}-input.json and {bundler}-output.json log files for inspecting inputs and outputs.

Try another bundler

Sometimes packages don't work with the default bundler. You can try another bundler for the specific package as follows:

# General syntax:
cloudpack bundle --match <package-name@version> --bundler <bundler>

# Bundle foo@1.2.3 with rspack:
cloudpack bundle --match foo@1.2.3 --bundler rspack

If another bundler works but the original does not, you can force that bundler for that particular package using a cloudpack.config.json package setting:

{
  "packageSettings": [
    {
      "match": { "name": "package-name", "version": "^1.0.0" },
      "bundler": "rspack"
    }
  ]
}

Specific issues

Inlining package content that can't be imported through ESM

Cloudpack tries to bundle packages in isolation, resolving them in the browser. However sometimes, this becomes impossible. For example, a SASS @import statement can't be resolved in the browser. Packages that export const enums can't provide those const enums in the browser, as they compile out.

To resolve these cross package dependencies that can only be resolved at build time, Cloudpack offers a way to describe a dependency to be included in package bundle output, rather than externalized:

{
  "packageSettings": [
    {
      "match": "package-name",
      "inlineDependencies": ["dependency-name"]
    }
  ]
}

Include a missing dependency

Sometimes the inner loop can require devDependencies. By default, Cloudpack ignores the devDependencies, assuming that all applications will list actual dependencies. To work around this, packageSettings can be provided to allow some devDependencies to be included in the importMap resolution:

{
  "packageSettings": [
    {
      "match": { "name": "package-name" },
      "includedDependencies": ["dependency-name"]
    }
  ]
}

Verify exports errors

verifyExports is a feature that verifies the exports of packages during init, specifically that consumed named imports exist as an export in the target package. It generates errors when a package imports something that isn't exported by the consumed package. These errors look like the following:

foo@1.0.0 - /monorepo/packages/foo
✗ 1 error
  ✗ [verify exports]
      A bundle imported names from another bundle which were not exported:
        • Importing bundle: /user/.cloudpack/foo-1.0.0-hash/lib/index.js
        • Importing source: /monorepo/packages/foo/src/index.ts
        • Exporting package: bar@1.0.0
        • Exporting bundle: /user/.cloudpack/bar-1.0.0-hash/lib/index.js
        • Exporting source: /monorepo/node_modules/bar/lib/index.js
        • Missing export(s): { baz }

If you're getting verify exports errors, you can try to fix them by:

• Verifying that the package actually exports the missing name.
  • To see which exports Cloudpack detected that the package produces and consumes, look at the bundle-info.json in the corresponding bundle cache folder. (One way to find this folder is by bundling the specific package, which will print the output folder path: yarn cloudpack bundle --match bar@1.0.0)
  • You can also look at the original package source to see if it actually produces an export name that Cloudpack isn't detecting. (If you find a case like this, please file an issue.)
• Verifying that the installed version of the dependency matches the requested range from the consuming package. In some cases, yarn resolutions are used to force a dependency version which violates semver, which can create problems if there have been breaking API changes between the requested and installed versions.

If the above steps don't resolve the issue, you can use ignoreMissingExports to ignore the verify exports errors for specific packages (and for specific exports):

{
  "packageSettings": [
    {
      "match": "package-name",
      "ignoreMissingExports": true
    }
  ]
}

Ori bundling timeout

If you're using ori as a bundler (default bundler on ESM packages), you may encounter a timeout error when bundling such as this:

✗ 1 error
  ✗ [ori]
      Exception while bundling: Error: Received no notification within the timeout window of 10000ms

Ori is set up with a default timeout of 10 seconds. If bundling a package times out, it will retry with a 20 second timeout.

If you're encountering this error repeatedly on specific packages, you can increase the timeout by adding a package setting:

{
  "packageSettings": [
    {
      "match": "package-name",
      "bundler": "ori",
      "bundlerOptions": {
        "buildAcknowledgeTimeoutMs": 30000
      }
    }
  ]
}

You can also try to individually bundle the package with the command cloudpack bundle --bundler ori --match package-name to try to figure out why it is slow.

File appears to be an ES module that was loaded with require

What's happening

This error occurs when a CommonJS (CJS) package tries to require() an ES module. This is a fundamental limitation - since require() is synchronous, it cannot load ES modules which are inherently asynchronous (view this post to learn more).

This issue typically appears when Cloudpack tries to run a CJS package in a worker process to analyze its exports for generating an ESM stub.

TIP

The package source code might be valid TypeScript ESM, but if the package is published as CJS with no ESM entries, it will be treated as such. Learn more about module formats

Solution options

1. Use a library with proper ESM support

The ideal solution is to use a library that also distributes ESM code with an exports map or a module field in package.json.

If you encounter a library without ESM support:

• Consider reaching out to the library maintainers: Many maintainers are responsive to ESM distribution requests as browser-compatibility becomes increasingly important.
• Open an issue: Politely explain that you're using their library in a browser context with Cloudpack and would benefit from ESM distribution.

While waiting for ESM support, see the alternative solutions below.

2. Bundle the dependency inline (recommended for limited usage)

If the problematic library is only used by a few packages, you can inline the dependency using webpack or rspack as they can handle this situation better. You can do this by adding a package setting in your cloudpack.config.json:

{
  "packageSettings": [
    {
      "match": { "name": "package-name" },
      "bundler": "rspack",
      "inlineDependencies": ["problematic-dependency-name"]
    }
  ]
}

This approach embeds the dependency directly into your package's bundle rather than trying to load it separately, skipping the need for an ESM stub.

WARNING

When inlining dependencies, the package will be duplicated if any other package also uses it. This usually doesn't cause issues for utility libraries, but can create problems if the inlined package defines a React context, maintains global state, or uses any other mechanism that needs to be shared across your application. In such cases, consider option #3 instead.

3. Manually specify exports (for widely used dependencies)

If option 2 isn't feasible because the dependency is widely used, you can use the unsafeCjsExportNames package setting to skip the ESM stub generation.

Option 3a: Manually specify export names

If you know exactly what the package exports, you can manually specify them:

{
  "packageSettings": [
    {
      "match": "problematic-dependency-name",
      "unsafeCjsExportNames": {
        "./index.js": ["exportName1", "exportName2"],
        "./other-entry.js": ["otherExport1", "otherExport2"]
      }
    }
  ]
}

Option 3b: Auto-generate from TypeScript definitions

If the package has TypeScript declaration files (.d.ts), you can automatically extract exports from the type definitions:

{
  "packageSettings": [
    {
      "match": "problematic-dependency-name",
      "unsafeCjsExportNames": "types"
    }
  ]
}

This approach:

• Parses the package's .d.ts files to find all exported names
• Automatically includes exports from re-exported files within the same package
• Saves you from manually listing exports, especially for packages with many exports or exports that change frequently

Could not resolve file with web extensions

If you encounter resolution errors for files that exist with .web.ts, .web.js, or similar web-specific extensions, this indicates that the bundler is not configured to recognize these extensions.

Could not resolve "./file"

What's happening

This error occurs when your code imports a file without an extension, but the actual file has a web-specific extension like .web.ts or .web.js. The bundler cannot resolve the import because it's not configured to check for web-specific file extensions.

Solution

Enable the resolve-web-extensions bundler capability in your cloudpack.config.json:

{
  "packageSettings": [
    {
      "match": "package-name",
      "bundlerCapabilities": {
        "resolve-web-extensions": true
      }
    }
  ]
}

This capability enables React Native-style resolution where bundlers will automatically look for .web.ts, .web.js, .web.tsx, and .web.jsx extensions when resolving imports without explicit extensions.

Note: This setting should be applied to the specific package that contains the web-specific files as it affects performance.