Initial import
This commit is contained in:
Admin
@@ -0,0 +1,172 @@
|
||||
---
|
||||
title: Troubleshooting
|
||||
---
|
||||
|
||||
Common issues and solutions when working with Quartz.
|
||||
|
||||
## Build Errors
|
||||
|
||||
### `Could not resolve ...` or missing module errors
|
||||
|
||||
This usually means a plugin is not installed. Run:
|
||||
|
||||
```bash
|
||||
npx quartz plugin install
|
||||
```
|
||||
|
||||
This restores all plugins from your `quartz.lock.json` to `.quartz/plugins/`.
|
||||
|
||||
### `tsc` type errors after updating
|
||||
|
||||
After running `npx quartz upgrade`, type errors can occur if the update changed internal APIs that your `quartz.ts` overrides depend on. Check the changelog for breaking changes and update your overrides accordingly.
|
||||
|
||||
### Build is slow
|
||||
|
||||
Try increasing concurrency:
|
||||
|
||||
```bash
|
||||
npx quartz build --concurrency 8
|
||||
# or the shorthand:
|
||||
npx quartz build -c 8
|
||||
```
|
||||
|
||||
The default uses all available CPU cores. If you're on a memory-constrained environment (CI), reducing concurrency may actually help.
|
||||
|
||||
## Plugin Issues
|
||||
|
||||
### Plugin not loading after installation
|
||||
|
||||
1. Verify the plugin appears in `quartz.config.yaml` under `plugins:`
|
||||
2. Check that `enabled: true` is set
|
||||
3. Run `npx quartz plugin list` to confirm it's installed
|
||||
4. Run `npx quartz plugin install --latest --dry-run` to verify plugin health
|
||||
|
||||
### Plugin options not taking effect
|
||||
|
||||
Make sure your YAML indentation is correct. Options must be nested under the plugin entry:
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- source: github:quartz-community/some-plugin
|
||||
enabled: true
|
||||
options:
|
||||
myOption: value # correct: nested under options
|
||||
```
|
||||
|
||||
A common mistake is putting options at the wrong indentation level.
|
||||
|
||||
### `ExternalPlugin.X is not a function`
|
||||
|
||||
This means the plugin is referenced in `quartz.ts` but not installed. Either:
|
||||
|
||||
- Install it: `npx quartz plugin add github:quartz-community/plugin-name`
|
||||
- Or remove the reference from `quartz.ts`
|
||||
|
||||
### Plugins fail to build on a fresh clone
|
||||
|
||||
> [!important]
|
||||
> Most community plugins now ship with a pre-built `dist/` directory and skip the build step entirely. The build failure scenario described below mainly applies to plugins in development or older plugins that haven't adopted pre-built distribution.
|
||||
|
||||
On a brand-new clone, `npx quartz plugin install` (or the plugin step run automatically by `npx quartz create`) may report a handful of plugins failing to build — typically around 10–15 of them. The git clone and checkout still succeed, but `npm run build` inside the plugin errors out.
|
||||
|
||||
This happens because `quartz.lock.json` pins each plugin to a specific commit, and those older plugin commits may have been authored against earlier versions of `@quartz-community/types` / `@quartz-community/utils` whose published artifacts are no longer shipped in the dependency's git repo. The plugin's `tsup`/`tsc` build then cannot resolve the expected type declarations.
|
||||
|
||||
Fix it by refreshing all plugins to the latest commit on their default branch:
|
||||
|
||||
```bash
|
||||
npx quartz plugin install --latest
|
||||
```
|
||||
|
||||
This rewrites `quartz.lock.json` with the newest commits (which in turn pin newer `@quartz-community/*` versions whose built output is available), and rebuilds every plugin from scratch. After this step, subsequent `npx quartz plugin install` calls will restore cleanly from the refreshed lockfile.
|
||||
|
||||
### `plugin install` hangs, OOMs, or fails on low-end hardware
|
||||
|
||||
> [!note]
|
||||
> Pre-built plugins are much faster and lighter on resources because they skip the `npm install` and `npm run build` steps.
|
||||
|
||||
By default, `npx quartz plugin install` clones, fetches, and builds plugins in parallel across all your CPU cores. Each parallel worker may run its own `npm install` and `npm run build`, which is memory-intensive. On low-end laptops, Raspberry Pi, small VPS instances, or restrictive CI runners this can exhaust RAM, trigger the OOM killer, or make the system appear to hang.
|
||||
|
||||
Lower the parallelism with `--concurrency` / `-c`:
|
||||
|
||||
```bash
|
||||
# Install one plugin at a time (safest, slowest)
|
||||
npx quartz plugin install --latest -c 1
|
||||
|
||||
# Two at a time — usually works on 4 GB machines
|
||||
npx quartz plugin install --latest --concurrency 2
|
||||
```
|
||||
|
||||
The same flag works for `plugin add` and the deprecated aliases (`plugin update`, `plugin restore`, `plugin check`, `plugin resolve`):
|
||||
|
||||
```bash
|
||||
npx quartz plugin add github:quartz-community/some-plugin -c 1
|
||||
```
|
||||
|
||||
If `plugin install` consistently fails near the same plugin with `-c 1`, the issue is likely with that specific plugin's build, not with concurrency — try running `--verbose` to get detailed error output, and check the plugin's own repository for known issues.
|
||||
|
||||
## Content Issues
|
||||
|
||||
### Notes not showing up
|
||||
|
||||
- Check that the file is in the `content/` folder
|
||||
- Check that `draft: true` is not set in the frontmatter (the [[RemoveDrafts]] plugin filters these out)
|
||||
- If using [[ExplicitPublish]], make sure `publish: true` is set in frontmatter
|
||||
- Check your [[configuration]] `ignorePatterns` to make sure the file path is not excluded
|
||||
|
||||
### Wikilinks not resolving
|
||||
|
||||
- Make sure the [[ObsidianFlavoredMarkdown]] plugin is enabled
|
||||
- Verify the target note exists in your content folder
|
||||
- Check for case sensitivity issues in filenames
|
||||
|
||||
### Images not displaying
|
||||
|
||||
- Ensure images are in a folder that Quartz processes (typically `content/` or a subfolder)
|
||||
- Check that the image path in your Markdown matches the actual file location
|
||||
- The [[Assets]] emitter must be enabled (it is by default)
|
||||
|
||||
## GitHub Sync Issues
|
||||
|
||||
### `fatal: --[no-]autostash option is only valid with --rebase`
|
||||
|
||||
You may have an outdated version of `git`. Update git to resolve this.
|
||||
|
||||
### `fatal: The remote end hung up unexpectedly`
|
||||
|
||||
This is usually due to Git's default buffer size being too small for your content. Increase it:
|
||||
|
||||
```bash
|
||||
git config http.postBuffer 524288000
|
||||
```
|
||||
|
||||
### Merge conflicts during sync
|
||||
|
||||
If `npx quartz sync` encounters merge conflicts:
|
||||
|
||||
1. Resolve the conflicts in your editor
|
||||
2. Run `git add .` and `git commit` to complete the merge
|
||||
3. Run `npx quartz sync --no-pull` to push
|
||||
|
||||
If you want to start over, run `npx quartz restore` to recover your content from the cache.
|
||||
|
||||
## Development Server Issues
|
||||
|
||||
### Hot reload not working
|
||||
|
||||
- Make sure you're using `--serve` mode: `npx quartz build --serve`
|
||||
- Check that port 3001 (WebSocket) is not blocked — this is the default `--wsPort` used for hot reload notifications
|
||||
- If developing remotely, use `--remoteDevHost` to set the correct WebSocket URL
|
||||
|
||||
### Port already in use
|
||||
|
||||
Change the port:
|
||||
|
||||
```bash
|
||||
npx quartz build --serve --port 3000
|
||||
```
|
||||
|
||||
## Still stuck?
|
||||
|
||||
- Check the [GitHub Issues](https://github.com/jackyzha0/quartz/issues) for similar problems
|
||||
- Ask in the [Discord Community](https://discord.gg/cRFFHYye7t)
|
||||
- Run your command with `--verbose` for more detailed error output
|
||||
Reference in New Issue
Block a user