Troubleshooting

Most problems come from Zendesk permissions, browser settings or the size of the help center. The Activity screen shows the exact error text for anything that failed.

"Zendesk is rate limiting requests"
"Zendesk refused this action" (403)
Read-only banner
The print window does not open
Downloads are blocked
The content blocks warning
Restoring an archived article
Several brands
Large help centers and memory
External links "could not be verified"
Clearing local data

"Zendesk is rate limiting requests"

Zendesk allows a fixed number of API requests per minute per account, shared by every app and integration. The app keeps its own requests under a rolling budget and, when Zendesk answers with a rate-limit error, waits for the time Zendesk asks and halves its pace. A scan or a batch of writes therefore slows down rather than fails. If it keeps happening, another integration is probably busy; try again in a few minutes or run large batches outside peak hours.

"Zendesk refused this action: your role does not have permission" (403)

Your Zendesk role cannot perform that write. Common cases:

Editing an article whose permission group does not include you. Ask a Guide admin to apply the change, or to add you to the group.
Changing the permission group or user segment of an article, which needs Guide admin rights.
Creating a draft from a template in a section you cannot edit.

Failed writes are not applied; the snapshot covers the successful ones, and the app stops after five failures in a batch so you can fix the cause first.

Read-only banner

When the app opens it reads your Zendesk role. If the role cannot edit articles, a "Read-only" banner appears and the apply dialog does not run. Scans, findings, previews and documents still work. If you believe the role is wrong, sign out and in again; the app assumes you can edit when it cannot read your role at all.

Print / Save as PDF opens the document in a new window. If your browser blocks pop-ups from Zendesk, the app downloads the document as an HTML file instead. Open that file and print from there, or allow pop-ups for your Zendesk subdomain and try again.

Downloads are blocked

Snapshots, documents, settings and template exports are files your browser downloads. If nothing appears, check the download bar or the browser's download settings, and allow downloads from your Zendesk subdomain. Some company policies block downloads inside iframes; in that case ask your IT team to allow them for *.zendesk.com. The snapshot is your safety net, so make sure downloads work before applying a large batch.

The content blocks warning

Content blocks are a Guide Enterprise feature. When an article body is saved through the Zendesk API, any content block in it is converted to plain content, and the API gives no way to detect which articles use them. So before any change that rewrites a title or body, the app asks you to confirm that the affected articles do not use content blocks, or that you accept the conversion. If you use content blocks, apply metadata fixes freely (labels, sections, publish state, promotion, translation status) and make body changes in the editor. If you never use content blocks, turn on "Do not ask about content blocks again" in Settings.

Restoring an archived article

Archiving through the API is the same as archiving in Guide: the article disappears from the help center and can be restored in Guide. Open Guide, go to Manage articles, choose the Archived list, find the article and restore it. The app's Undo cannot do this, which is why archiving asks for a separate acknowledgement.

Several brands

Version 1.0 scans the help center of the account subdomain you are signed in to. Other brands are listed in Settings and on the Scan screen but not scanned. To check another brand, open Zendesk Support on that brand's subdomain and open the app there. Multi-brand scanning is planned for the Business plan.

Large help centers and memory

The scan keeps a working copy of every article and translation in memory and in browser storage. Help centers with many thousands of articles in several languages can take a few minutes and a few hundred megabytes of memory. Tips:

Use Refresh changed articles after the first scan instead of a full rescan.
Close other heavy tabs while scanning or applying large batches.
Run the external link check separately and let it use the 7-day cache.
If the browser reports that storage is full, the app keeps working for the session without caching; clear local data or free up space.
Narrow find and replace with the language filter on very large centers so previews stay quick.

External links "could not be verified"

The link checker sends a small request through Zendesk's proxy and waits up to 15 seconds (adjustable). Sites that require a login, use bot protection (many sites behind Cloudflare), answer with a server error or time out are reported as unverified, never as broken. Open the link in your browser; if it works, add the host to Never check these hosts in Settings. Only 404 and 410 answers are reported as broken.

Clearing local data

Settings, Data and privacy, Clear local data removes the cached scan, link results, templates, settings and the activity log for this Zendesk account from this browser. Export your settings and templates first if you want to keep them. Your help center is not touched. Uninstalling the app does not clear browser storage by itself; use this control first, or clear site data for your Zendesk subdomain in the browser afterwards.

Not solved? Contact support with the error text from the Activity screen.