mirror of
https://github.com/jackyzha0/quartz.git
synced 2026-03-22 05:55:42 -05:00
129 lines
3.8 KiB
Markdown
129 lines
3.8 KiB
Markdown
---
|
|
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 restore
|
|
```
|
|
|
|
This restores all plugins from your `quartz.lock.json` to `.quartz/plugins/`.
|
|
|
|
### `tsc` type errors after updating
|
|
|
|
After running `npx quartz update`, 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
|
|
```
|
|
|
|
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 check` 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`
|
|
|
|
## 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
|