Common Issues

This is a list of common/somewhat-cryptic issues that you may encounter while working on a project. Please update this list with any issues you encounter that aren’t listed here that you think others may encounter.

Astro

• Expected > but found x
  • Potential cause: TypeScript definitions that include angle brackets spanning multiple lines in .astro files.
  • Fix: Shortening the definition by splitting it up or adding a prettier-ignore comment.

Building Packages

• x does not provide export y

  • Potential cause: That a package is missing

  {
  	"type": "module"
  }

  in its package.json file. This is required for outputted ESM files to be generated correctly.

Caprover

• Build failed, out of memory or operation failed, out of memory.
  • Potential cause: As indicated by the message, the system is likely out of hard drive space.
  • Fix: The built-in Caprover image cleanup is fairly basic, and more storage can be freed up with docker pruning. See Caprover Disk Cleanup for more details.
• Something bad happened or Caprover is not ready yet
  • Potential cause This typically means that an app’s build failed catastrophically.
  • Fix: These errors will usually also occur when building locally, and that will provide a much more helpful debugging experience. (I’m not sure what causes these errors instead of the build process simply failing.)

Composer

• Composer asks for a password for public packages

  • Potential cause: Composer may use GitHub credentials to avoid rate limiting for hosted packages.
  • Fix: Add a GitHub Token.

• Composer repeatedly asks for a token despite being given a working token.

  • Potential cause: Multiple tokens were registered with overlapping scopes that have different validity.
  • Fix Check ~/.composer/auth.json to verify scopes and tokens are correct.

Docker

• Environment variables missing during build (When using Turbo Repo).
  • Potential Cause: Environment variables provided by the system (ie. not a .env file) need to be declared in turbo.json to be present at build time.
  • Fix: Add the variable to the globalEnv array in turbo.json.

JavaScript

• undefined is not a function or someName is not a function
  • Potential cause: This typically means that whatever data was supposed to have a function called on it isn’t there. Fix: In the case of name is not a function, check the spelling/correct method, in the case of undefined is not a function check the lead up to the call to make sure the data you think is there is actually there.
• Cannot access property of undefined, accessing x
  • Potential cause: This means that in the case of console.log(whatever.x) or console.log(whatever.somethingElse.x) either whatever (in the first case) or somethingElse in the (second case) doesn’t exist. The problem is unrelated to x itself.
• [object Object]
  • Potential cause: An object was cast to a string.
  • Fix: This is typically a mistake with which data should be used, however, if you really did want to cast the object to a string, use JSON.stringify() or console.dir().
• Cannot find module x or its corresponding type declarations. There are types at y, but could not be resolved under your current moduleResolution setting.
  • Potential cause: This can be caused if the file in which the error is occurring is not included by the tsconfig.json file that is specifying moduleResolution:"bundler".
  • Fix: Add the file to the include array in the tsconfig.json file.
• Types are exported but not showing up in the consuming file.
  • Potential cause: Types emitted with tsc do not have aliased paths replaced.
  • Fix: Do not rely on the aliased paths in the tsconfig.json file. Instead, use relative paths when exporting types or code that types are derived from (for example, a Zod schema).

PostCSS

• Styles from CSS files that were imported don’t appear in the outputted CSS.
  • Potential cause: Transpiling done by the PostCSS CLI do not follow or include imports by default.
  • Fix: Add the postcss-import plugin to the PostCSS configuration file.

Tailwind CSS

• @apply rules don’t turn into CSS.
  • Potential cause: This occurs when the @apply directive is in a file that relies on CSS @import.
  • Fix: This can be circumvented by changing imported files to SASS.
  • Note With Tailwind CSS v4+ this shouldn’t be an issue
• Some utility classes aren’t generated while others in the same source file are
  • Potential cause `@import “tailwindcss/theme” is missing
  • Fix Add that import. Classes that rely on theme variables won’t generate if the theme isn’t imported.
• Tailwind utilities are being loaded into layers and getting overwritten by less specific rules.
  • Potential cause By default, @import 'tailwindcss adds layers to its sub-components.
  • Fix Import the three sub-components separately to control the layers.

webpack

• TypeError: The 'compilation' argument must be an instance of Compilation
  • Potential cause: This typically indicates that there are multiple versions of webpack installed.
  • Fix Make sure that any other dependencies using webpack have it flagged as a peer dependency. This was previously an issue in @rootreeweb/rt-webpack-helper.
• Module build failed: UnhandledSchemeError: Reading from "node:fs" or Module build failed: UnhandledSchemeError: Reading from "node:path"
  • Potential cause: This typically occurs when a package is trying to read from a Node.js core module (fs, path, etc.).
  • Fix (Next.js): This can be resolved by dropping the node: prefix from the import and ensuring that the code in question is only executed on the server.
  • Fix (Webpack): If the package is meant to run in the browser only, you cannot use Node.js core modules.
• A 404 (file not found) error for a file that is not present in the source, the bundle, or the webpack manifest
  • Potential cause: This can happen if a CSS custom property is used that references a file outside the project being bundled.
    • For example, the project uses background-image: var(--image-path); and the --image-path: url(../assets/file.png) is defined in another project.
  • Fix: Ensure that the file is included in the project that is being bundled.

Yarn

• package-name can't be resolved to a satisfying range
  • Potential cause: This can occur when the package and/or version specified do not exist.
  • Fix: Check the package name and version specified in the package.json file for correctness.
  • Another potential cause It also occurs when the package is private, but the private registry wasn’t specified in the .yarnrc.yml configuration file.
  • Another fix: Check out the Using Our Private Packages guide for how to set that up.
• Invalid authentication (as an unknown user)
  • Potential cause: This is coupled with the error above, but is also a cryptic way of telling you that your access token is invalid or expired.
  • Fix: Check out the Using Our Private Packages guide for the details on generating a new token.
• Environment variable not found (GHACCESS)
  • Potential cause: This indicates that .yarnrc.yml is correctly configured for the private repository, but that the GHACCESS environment variable is not set.
  • Fix: Check out the Using Our Private Packages guide for the details on setting the environment variable.
• package-name is listed by your project with version x.x.x, which doesn't satisfy what other-package-name ...
  • Potential cause: Dependencies have conflicting secondary dependencies.
  • Fix: If everything works, this may be ignored. Otherwise, there isn’t anything that can be done unless they’re first-party packages. This issue also may persist after the conflict is resolved if old contents in yarn.lock are present.
• Command failed with exit code 137 (Usually on Caprover)
  • Potential cause: This typically means that the system is out of memory.
  • Fix This can be mitigated by temporarily disabling other apps to free up some memory.
• Command failed with exit code 139 (Usually while building a Docker image)
  • Potential cause: This typically means that permissions are not set correctly, or required files are missing.

Zod

• Cannot read properties of undefined (reading '_parse')

  • Potential cause: There are circular dependencies in schemas. This includes files that import each other, not necessarily a circular dependency in the schemas themselves.

• Type instantiation is excessively deep and possibly infinite. ts(2589)

  • Potential cause: There are multiple versions of zod in-use and conflicting with each other.
  • Fix: Upgrade the version in use where necessary, use peer dependencies where possible.