remix-run/remix · error · TypeError

assetServer.getHref() only supports transforms for configure

Error message

assetServer.getHref() only supports transforms for configured file assets

What it means

`remix new` requires exactly one positional: the target directory. `parseNewCommandArgs` allows at most one positional (`maxPositionals: 1`) and throws `RMX_MISSING_TARGET_DIRECTORY` when none is provided. The app name can come from `--app-name`, but the directory itself is mandatory and there is no interactive fallback.

Source

Thrown at packages/assets/src/lib/asset-server.ts:755

        }
        if (isAssetServerCompilationError(error) && error.code === 'FILE_TRANSFORM_QUERY_INVALID') {
          return new Response(error.message, {
            status: 400,
            headers: { 'Content-Type': 'text/plain; charset=utf-8' },
          })
        }

        return responseForError(error)
      }
    },

    async getHref(filePath, hrefOptions) {
      let transform = getHrefTransform(hrefOptions, resolvedOptions.files)
      let typeCheckFilePath = stripFilePathUrlSuffix(filePath)

      if (isStyleFilePath(typeCheckFilePath)) {
        if (transform !== null) {
          throw new TypeError(
            'assetServer.getHref() only supports transforms for configured file assets',
          )
        }
        return styleCompiler.getHref(filePath)
      }

      if (fileCompiler?.isServedFilePath(typeCheckFilePath)) {
        return fileCompiler.getHref(filePath, {
          transform,
        })
      }

      if (!isScriptFilePath(typeCheckFilePath)) {
        throw createAssetServerCompilationError(`File type is not supported: ${filePath}`, {
          code: 'FILE_NOT_SUPPORTED',
        })
      }

View on GitHub (pinned to 9696913134)

Solutions

1. Pass the target directory: `remix new my-app`
2. In scripts, quote and verify the variable is non-empty: `remix new "$APP_DIR"`
3. Optionally add `--app-name` alongside the directory

Example fix

# before
remix new
# after
remix new my-app

let dir = process.argv[2];
if (!dir || dir.trim() === '') {
  console.error('Usage: remix new <target-dir>');
  process.exit(1);
}
run(['remix','new',dir])

function isNonEmptyDirArg(dir: string | undefined): dir is string {
  return typeof dir === 'string' && dir.trim() !== '';
}

When it happens

Trigger: Running `remix new` with zero positionals — `parsed.positionals[0]` is undefined, `targetDir` is null, and the error throws before scaffolding.

Common situations: Assuming an interactive prompt will ask for a directory; CI scripts with an empty/unquoted variable for the path; the path accidentally consumed by a preceding flag.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• RMX_TARGET_DIRECTORY_NOT_EMPTY
• throw new AssertionError(options)
• ${matcherName} requires a mock function with a .mock.calls p
• throw new AssertionError({ message, actual, expected, operat
• expect(received).toThrow() requires a function (got ${typeof

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