Troubleshooting

scope:

• Common Quartz failure modes, causes, diagnostics, fixes.

Build Errors

Could not resolve ... or missing module errors

cause:

• Plugin missing from .quartz/plugins/.

fix:

• Restore plugins pinned in quartz.lock.json:

npx quartz plugin install

tsc type errors after updating

cause:

• npx quartz upgrade changed internal APIs used by quartz.ts overrides.

fix:

• Read the changelog.
• Update affected quartz.ts overrides for breaking API changes.

Build is slow

fix:

• Increase build concurrency:

npx quartz build --concurrency 8
# or the shorthand:
npx quartz build -c 8

notes:

• Default: all available CPU cores.
• Memory-constrained environments, especially CI, may build faster with lower concurrency.

Plugin Issues

Plugin not loading after installation

checks:

• quartz.config.yaml contains the plugin under plugins:.
• Plugin entry sets enabled: true.
• npx quartz plugin list shows the plugin installed.
• npx quartz plugin install --latest --dry-run reports healthy plugin state.

Plugin options not taking effect

cause:

• Incorrect YAML indentation.
• Options must nest under the plugin entry:

quartz.config.yaml

plugins:
  - source: github:quartz-community/some-plugin
    enabled: true
    options:
      myOption: value # correct: nested under options

fix:

• Move misplaced options under options:.

ExternalPlugin.X is not a function

cause:

• Plugin referenced in quartz.ts but absent from .quartz/plugins/.

fix:

• Install it: npx quartz plugin add github:quartz-community/plugin-name
• Or remove the quartz.ts reference.

Plugins fail to build on a fresh clone

Important

Most community plugins ship a prebuilt dist/ directory and skip builds. This mainly affects in-development plugins and older plugins without prebuilt distribution.

symptom:

• Fresh npx quartz plugin install, or the automatic plugin step in npx quartz create, reports several plugin build failures, often 10–15.
• Git clone and checkout succeed.
• npm run build inside affected plugins fails.

cause:

• quartz.lock.json pins each plugin to a commit.
• Older commits may depend on earlier @quartz-community/types / @quartz-community/utils versions whose built artifacts no longer exist in the dependency git repo.
• Plugin tsup / tsc builds cannot resolve expected type declarations.

fix:

• Refresh all plugins to latest default-branch commits:

npx quartz plugin install --latest

effect:

• Rewrites quartz.lock.json with newest plugin commits.
• Pins newer @quartz-community/* versions with available built output.
• Rebuilds every plugin from scratch.
• Future npx quartz plugin install restores cleanly from the refreshed lockfile.

plugin install hangs, OOMs, or fails on low-end hardware

Note

Prebuilt plugins use fewer resources because they skip npm install and npm run build.

cause:

• npx quartz plugin install clones, fetches, and builds plugins in parallel across all CPU cores.
• Each worker may run its own npm install and npm run build.
• Parallel builds can exhaust RAM, trigger the OOM killer, or appear hung.

affected:

• Low-end laptops.
• Raspberry Pi.
• Small VPS instances.
• Restrictive CI runners.

fix:

• Lower parallelism with --concurrency / -c:

# 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

applies_to:

• plugin add
• Deprecated aliases: plugin update, plugin restore, plugin check, plugin resolve

npx quartz plugin add github:quartz-community/some-plugin -c 1

diagnosis:

• If plugin install -c 1 fails near the same plugin repeatedly, suspect that plugin’s build, not concurrency.
• Run with --verbose.
• Check the plugin repository for known issues.

Content Issues

Notes not showing up

checks:

• File lives under content/.
• Frontmatter does not set draft: true; RemoveDrafts filters drafts.
• If using ExplicitPublish, frontmatter sets publish: true.
• configuration ignorePatterns does not exclude the file path.

Wikilinks not resolving

checks:

• ObsidianFlavoredMarkdown is enabled.
• Target note exists under content/.
• Filename casing matches link casing.

Images not displaying

checks:

• Image lives in a Quartz-processed folder, usually content/ or a subfolder.
• Markdown image path matches the actual file path.
• Assets emitter is enabled; default: enabled.

GitHub Sync Issues

fatal: --[no-]autostash option is only valid with --rebase

cause:

• Outdated git.

fix:

• Update git.

fatal: The remote end hung up unexpectedly

cause:

• Git default buffer too small for repository content.

fix:

• Increase buffer:

git config http.postBuffer 524288000

Merge conflicts during sync

trigger:

• npx quartz sync encounters merge conflicts.

fix:

• Resolve conflicts in an editor.
• Run git add ..
• Run git commit.
• Run npx quartz sync --no-pull.

reset:

• Run npx quartz restore to recover content from cache.

Development Server Issues

Hot reload not working

checks:

• Use serve mode: npx quartz build --serve.
• Port 3001 is unblocked; default --wsPort for hot reload notifications.
• Remote development: set --remoteDevHost to the correct WebSocket URL.
• TLS reverse proxy for remote development: set --wsPublicPort to the public port, default 3002, and --wsPort to the local bind port.

Port already in use

fix:

• Change the port:

npx quartz build --serve --port 3000

Still stuck?

next_steps:

• Search GitHub Issues.
• Ask in the Discord Community.
• Rerun the failing command with --verbose.