> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://usekeltra.vercel.app/api/mcp` to find what you need.
>
> **Have feedback?** Use `submit_feedback` on the same MCP server.

# Troubleshooting \[Fix the most common problems]

## No autocomplete, and typos aren't caught

Paths are plain strings when TypeScript doesn't load `.keltra/register.d.ts`. Check these in order:

1. **The manifest exists.** Start your dev server or run `npx keltra generate`, then look for `.keltra/register.d.ts`.

2. **Your tsconfig includes it.** Use `".keltra/*.d.ts"`. The shorter `".keltra"` loads nothing, because TypeScript skips folders that start with a dot.

   ```json [tsconfig.json]
   {
     "include": ["src", ".keltra/*.d.ts"]
   }
   ```

3. **The editor picked up the change.** Restart the TypeScript server (in VS Code: run "TypeScript: Restart TS Server").

## A file isn't in the autocomplete list

* **Folder:** it must be inside one of your configured `dirs`. The default is `public`.
* **Extension:** only listed extensions are scanned. See the defaults in [Configuration](/reference/config), and add yours with `extensions`.
* **Hidden files:** files and folders whose names start with a dot are skipped.
* **Ignored:** check your `ignore` patterns.
* **Same path twice:** if two folders produce the same path, the first folder in `dirs` wins.

## "Could not load your keltra config"

`keltra.config.ts` threw while loading. Common causes are a syntax error, or importing `keltra` before it is installed. Run your package manager's install command, then try again. The message includes the underlying error.

## Images 404 on the deployed site

If the site is served from a sub-path, set Vite's `base` to match. See [Deployment](/guides/deployment). The base is applied at build time, so rebuild after changing it.

## `fetchPriority` warning in the console

The `priority` prop on `Img` sets `fetchPriority="high"`, which React 18 doesn't recognize. Upgrade to React 19 or leave `priority` off.

## Next.js can't resolve keltra in a monorepo

Turbopack only reads files inside its project root. If your app imports `keltra` through a workspace link and the build says it can't resolve `keltra` or `keltra/image/next`, make sure your repository has a lockfile at its root, which is how Next.js finds the workspace root. You can also set `turbopack.root` in `next.config.ts` to the repository root.

## "`NextConfig` is not assignable to `NextConfigInput`" in a monorepo

`withKeltra` accepts a `NextConfig`, but TypeScript complains that the `NextConfig` from one copy of `next` isn't assignable to the `NextConfig` from another:

```
Argument of type 'NextConfig' is not assignable to parameter of type 'NextConfigInput | undefined'.
  Type 'import("…/next@16.4.5+7a5db38…/next/dist/server/config-shared").NextConfig' is not assignable to type
       'import("…/next@16.4.5+cba3cb3…/next/dist/server/config-shared").NextConfig'.
    Types of property 'webpack' are incompatible.
      …
```

This isn't a keltra bug. Your monorepo has two physical copies of the same `next` version installed — typically different peer-dependency hashes in Bun's `.bun` store, or two entries under pnpm's isolated linker. Because the two `NextConfig` declarations live in separate directories, TypeScript treats them as unrelated types and refuses to pass one where the other is expected.

You can fix it at the call site (fastest) or at the install level (removes the duplicate entirely).

::::steps
### Use `satisfies` instead of a type annotation

Replace the `: NextConfig` annotation with `satisfies NextConfig`. This checks the object against `NextConfig` without widening its inferred type, so the value stays assignable to both copies.

```ts [next.config.ts]
import { withKeltra } from "keltra/next";
import type { NextConfig } from "next";

const nextConfig = {
  /* config options here */
} satisfies NextConfig;

export default withKeltra(nextConfig);
```

The same works inside `withKeltra`'s callback form:

```ts [next.config.ts]
import { withKeltra } from "keltra/next";
import type { NextConfig } from "next";

export default withKeltra((phase, { defaultConfig }) => ({
  ...defaultConfig,
  /* config options here */
}) satisfies NextConfig);
```

### Deduplicate `next`

To keep the `: NextConfig` annotation, remove the duplicate copy so there's only one `NextConfig` type in the project:

:::code-group
```bash [npm]
npm dedupe
```

```bash [pnpm]
pnpm dedupe
```

```bash [yarn]
yarn dedupe
```

```bash [bun]
bun dedupe
```
:::

If the copies survive because the workspaces resolve different peer sets, pin `next` in the **root** `package.json` and reinstall:

```json [package.json]
{
  "overrides": {
    "next": "16.4.5"
  }
}
```

```bash
rm -rf node_modules && bun install   # or pnpm install / npm install
```

After that, the original `const nextConfig: NextConfig = { … }` form type-checks again.
::::

## The manifest keeps showing up in git

Add `.keltra/` to your `.gitignore`. `keltra init` does this for you when a `.gitignore` already exists.