remix-run/remix · error · CliError

Asset configuration is missing from remix.json.

Error message

Asset configuration is missing from remix.json.

What it means

The remix assets subcommand requires an assets configuration block, but remix.json (or the loaded config file) has no assets key, so no asset server can be constructed. This is a configuration prerequisite error, not a runtime failure.

Source

Thrown at packages/cli/src/lib/commands/assets.ts:26

  assetsConfigRequired,
  invalidOptionValue,
  renderCliError,
  toCliError,
  unknownCommand,
} from '../errors.ts'
import { formatHelpText } from '../help-text.ts'
import { parseArgs } from '../parse-args.ts'

export async function runAssetsCommand(argv: string[], context: CliContext): Promise<number> {
  if (argv.includes('-h') || argv.includes('--help')) {
    process.stdout.write(getAssetsCommandHelpText())
    return 0
  }

  try {
    let invocation = parseAssetsCommandArgs(argv)
    let config = await context.loadConfig()
    if (config.assets === undefined) throw assetsConfigRequired()

    let assetServer = createAssetServer({ ...config.assets, watch: false })
    try {
      let rootDir = fs.realpathSync(config.assets.rootDir)

      if (invocation.command === 'list') {
        process.stdout.write(formatAssetList(await assetServer.getAssets(), rootDir))
      } else {
        process.stdout.write(
          formatAssetDetails(await assetServer.getAssetDetails(invocation.input), rootDir),
        )
      }
    } finally {
      await assetServer.close()
    }

    return 0
  } catch (error) {

View on GitHub (pinned to 9696913134)

Solutions

1. Add an assets section (rootDir, files.extensions, mounts as needed) to remix.json
2. Verify you are in the right project directory / using the intended --config file
3. Regenerate or copy the assets block from a working project template

Example fix

// before: remix.json
{ "app": { "root": "app" } }

// after
{ "app": { "root": "app" }, "assets": { "rootDir": ".", "mounts": { "/": "app" } } }

let config = await loadConfig()
if (config.assets === undefined) {
  throw new Error('Add an "assets" block to remix.json before running asset commands')
}

function hasAssetsConfig(config: unknown): config is { assets: object } {
  return typeof config === 'object' && config !== null && 'assets' in config && config.assets != null
}

try {
  await runAssetsCommand(argv, context)
} catch (error) {
  if (/missing from remix.json/i.test(error.message)) linkToAssetsDocs()
  else throw error
}

When it happens

Trigger: Running remix assets list or remix assets inspect in a project whose config lacks an assets section; config loaded from a custom --config file that omits assets.

Common situations: New projects scaffolded without the asset pipeline enabled; renaming or restructuring remix.json and dropping the assets block; pointing --config at the wrong file.

Related errors

• throw new AssertionError({ message, actual, expected, operat
• expect(received).toThrow() requires a function (got ${typeof
• expected promise to resolve, but it rejected with: ${stringi
• expected promise to reject, but it resolved with: ${stringif
• throw new TypeError(message)

AI-assisted analysis of remix-run/remix@9696913134 (2026-08-27). Data as JSON: /api/errors/2fca01ffa54496f7. Report an issue: GitHub.