Troubleshooting

The CLI requires an interactive terminal

Run npx docuwriter directly in an interactive terminal. Project confirmation, browser authorization, and setup require interaction.

--json changes the final output format; it does not remove the prompts. A noninteractive run returns action_required with exit code 2.

Also check that Node.js is 22.18.0 or later:

node --version

The browser did not open

Open the URL printed in your terminal. You can request this behavior deliberately:

npx docuwriter --no-open

Keep the terminal open while signing in or registering and approving access. If the authorization code expires, rerun the command to get a new one. If you declined the request, rerun it and approve the new request when you intend to continue.

My session expired or I need another account

Start a fresh authorization:

npx docuwriter login

To revoke the saved session first:

npx docuwriter logout

A pending upload belongs to the account that created it. If the CLI reports that it belongs to another account, sign in with that original account to resume or discard it.

If your account cannot upload, check your access on the platform. Viewer access does not allow project uploads.

An upload was interrupted

Run the command again from the intended project folder:

npx docuwriter

When a pending upload is found, choose:

  • Resume the approved snapshot to retry the saved snapshot. Its contents stay the same even if local files have since changed. The transfer may restart.
  • Discard and start a new upload to remove the pending snapshot and package the current files through a new setup.
  • Cancel to leave the pending upload for later.

If you want local edits made since the previous attempt to be included, discard the old snapshot and start again.

Explicitly cancelling an unaccepted upload with Ctrl+C aborts it and removes its pending snapshot. That differs from a recoverable network interruption. Once a snapshot has been accepted, follow progress in the Space URL rather than starting another upload solely because generation is still running.

The project is too large

Free-plan ZIP uploads support up to 1 GB. Upgrade to upload larger projects; paid accounts retain a 20 GB technical ceiling. Uncompressed project contents also have a technical limit.

Select a smaller folder or exclude unnecessary files with applicable .gitignore rules:

npx docuwriter --cwd ./packages/api

If a pending snapshot is too large, discard it before starting a smaller upload.

No files or Markdown documentation were found

Check that you selected the right folder. Applicable .gitignore rules, built-in exclusions, and platform exclusions can remove files from the selection.

For documentation imports:

  • Use .md or .markdown files containing valid UTF-8 text.
  • Select a discovered file/folder or enter a relative path inside the selected project.
  • Stay within 1,000 Markdown files, 5 MiB per Markdown file, and 10 MiB per supported local image.
  • Include linked Markdown pages in the import and keep local image targets inside the project.

Symlinks are not uploaded. See Import existing documentation and Privacy and file exclusions.

Files changed while packaging

If the CLI reports that project files changed while packaging, let the files settle and run the command again. Avoid modifying the selected files while the snapshot is being prepared.

I was told to update the CLI

Request the latest published launcher:

npx docuwriter@latest

Then repeat the workflow. --version reports the CLI implementation version, which can differ from the launcher package version.

Processing failed after the upload was accepted

Open the Space URL printed by the CLI and check its progress or failure message. Upload acceptance and completed documentation are separate steps.

For help, contact [email protected] or report a CLI issue. Include the relevant error and Support reference if one was printed. Do not include authorization codes, access tokens, credentials, or private source files in a public issue.

Updated