> ## Documentation Index
> Fetch the complete documentation index at: https://illegalcord.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Issues

> Troubleshoot source build, injection, plugin, theme, and settings problems in Illegalcord.

Most Illegalcord issues are easier to solve if you identify the layer first: dependencies, build output, desktop injection, web extension output, plugin state, or settings data.

## Dependency install fails

<Steps>
  <Step title="Check Node.js">
    Run `node -v`. Use Node.js 22 or newer.
  </Step>

  <Step title="Use the lockfile">
    Run dependency install from the repository root:

    ```bash theme={null}
    pnpm install --frozen-lockfile
    ```
  </Step>

  <Step title="Avoid mixed package managers">
    Do not install dependencies with `npm install` or `yarn` in this repo. The project is configured for `pnpm`.
  </Step>
</Steps>

## Desktop build fails

Run the build directly so you can read the first error:

```bash theme={null}
pnpm build
```

Then run targeted checks:

```bash theme={null}
pnpm testTsc
pnpm lint
pnpm lint:patches
```

<Tip>
  Patch failures are often caused by Discord changing bundled code. Use DEV output and Patch Helper when available to inspect the nearby source.
</Tip>

## Illegalcord does not appear in Discord settings

<Steps>
  <Step title="Confirm the desktop bundle builds">
    Run `pnpm build` and make sure it completes.
  </Step>

  <Step title="Run the injector">
    Run `pnpm inject` from the repository root.
  </Step>

  <Step title="Fully restart Discord">
    Quit Discord completely, including tray or background processes, then launch it again.
  </Step>

  <Step title="Repair if needed">
    If the settings section still does not appear, run:

    ```bash theme={null}
    pnpm repair
    ```
  </Step>
</Steps>

## Web build output is missing

Build the web target:

```bash theme={null}
pnpm buildWeb
```

Then inspect `dist`. If the build fails, run:

```bash theme={null}
pnpm testTsc
pnpm lint
```

Browser extension loading rules vary by browser. Make sure you are loading the generated extension output supported by your browser.

## A plugin breaks the client

<Steps>
  <Step title="Disable the last changed plugin">
    Open **Illegalcord Settings > Plugins** if the UI still loads, then toggle off the plugin you changed most recently.
  </Step>

  <Step title="Restore from backup">
    If you exported a settings backup, restore a known-good plugin configuration from **Backup & Restore**.
  </Step>

  <Step title="Check the console">
    Open Discord DevTools and inspect the Console for the plugin name and stack trace.
  </Step>

  <Step title="Fix source and rebuild">
    Edit the plugin source, run `pnpm build`, then restart Discord.
  </Step>
</Steps>

## A theme or QuickCSS breaks the UI

If the UI is still usable, open **Themes** or **Edit QuickCSS** and remove the last CSS change.

If the UI is not usable:

1. Open the settings folder from a previous known-good client if possible.
2. Remove the broken local theme file or clear the QuickCSS backup data you imported.
3. Rebuild and relaunch.

<Warning>
  Keep exported backups before large theme edits. CSS can hide controls you need to recover.
</Warning>

## Plugin metadata looks stale

After adding, moving, renaming, or removing plugins, regenerate plugin metadata:

```bash theme={null}
pnpm generatePluginJson
```

If you only changed one source family:

```bash theme={null}
pnpm generateEquicordPluginJson
pnpm generateVencordPluginJson
```

## TypeScript alias imports fail

Check `tsconfig.json` for the alias you are using. Common aliases include `@api/*`, `@components/*`, `@utils/*`, `@webpack`, `@webpack/common`, `@plugins/*`, and `@equicordplugins/*`.

Avoid deep relative imports when an alias exists.