Troubleshooting
Common issues and how to resolve them.
Quick lookup
Symptom | Section |
|---|---|
Publish slow or failed | |
Changes not showing on published site | |
PDF looks different from web | |
Version selector missing | |
Cannot delete a component | |
Component outdated on site | |
Filtered content missing | |
Variable tokens show key name | |
Cannot import files | |
Images missing after import | |
Formatting lost in import | |
Nested lists flattened | |
AI will not apply a change | |
Feature needs a higher tier | |
Cannot add team members | |
Analytics not visible | |
AI widget not showing | |
Cannot delete map version | |
Lost targets after version delete | |
Password reset | |
Search returns no results |
Publishing
My publish is taking a while or failed
Publishing runs as a background job. After you publish a target, the job works through several steps (building the site, generating images, computing AI-readiness scores, and indexing search) and reports progress. If a step fails, the job surfaces a failed state rather than hanging silently. Retry the publish, and if it keeps failing, contact support with the target name.
My changes are not showing on the published site
Edits you make to topics, filters, variables, or map structure reach a live published site through its cache, not through a manual republish. The cache refreshes automatically within 24 hours. To push changes live immediately, republish the target.
The Topicary documentation site at topicary.com updates through a separate sync process, so features computed at publish time (AI-readiness scores, embeddings, suggested links) can be absent there until it is republished.
My PDF looks different from the web output
PDF output uses print-specific CSS. Interactive elements (code tabs, search, dark mode) do not apply to PDF. Tables, images, and callouts may render with different spacing.
The version selector does not appear on my published site
The version selector only shows when two or more versions of the same map each have a published target. Publish at least two versions to enable it.
Components
I cannot delete a component
A component cannot be deleted while topics reference it. Check the where-used count on the Components page to see which topics reference it. Remove all references first, then delete the component.
My component shows outdated content on the published site
Component references are live in the editor, so you always see current content. A published site serves cached content that refreshes within 24 hours. To pick up component changes immediately, republish the target.
Filters and variables
Filtered content is not appearing in my published output
Check two things: (1) the content block has the correct filter applied in the editor (open the filter preview to verify), and (2) the publication target's filter profile includes the matching value. A block filtered on "Audience: Admin" only appears in targets where the filter profile includes Audience = Admin.
Filters were previously called "conditions" and are an Enterprise-tier capability. Variables are a Team-tier capability.
Use the filter preview in the editor to see exactly which blocks are visible for each filter profile. This lets you verify content visibility without publishing.
Variable tokens show the key name instead of the value
The publication target needs a variable set assigned. Go to the map editor, open the target settings, and select a variable set that defines the key used in the token.
Import
I cannot import files
Markdown, HTML, and DITA import on any tier. Importing Word, Confluence, MadCap Flare, or OpenAPI files requires the Team tier (advanced import). If those formats are blocked, this is a tier gate, not a bug: request Team access from Settings > Billing.
Images are missing after import
When you import a zip that contains images (for example, a Confluence or Flare export), the images are extracted and stored automatically. When you import a single Markdown or HTML file, image references are kept as URLs and local image files are not uploaded. In that case, re-upload the images using the image insert tool in the editor.
My import lost formatting
Complex formatting from the source tool may not transfer. Confluence macros (Jira links, dynamic content blocks, custom macros), Word tracked changes, and embedded objects are simplified or removed during import.
Source format | What transfers | What is lost or simplified |
|---|---|---|
Confluence | Headings, paragraphs, lists, tables, images, basic formatting | Macros (Jira links, dynamic content, custom), page trees, comments |
MadCap Flare | Topics, master TOC (as a map), snippets (as components), condition sets (as filters), variable sets, basic formatting | Skins and stylesheets, build targets, build logic |
Microsoft Word | Headings, paragraphs, lists, tables, basic formatting | Tracked changes, comments, embedded objects, complex styles |
Markdown | Full content with formatting | None (Markdown is the closest match to the internal format) |
Nested lists are flattened after import
Deeply nested lists from Confluence or Word may lose levels during conversion. Review imported topics and manually adjust list indentation where needed.
AI editing
AI will not apply its suggested change to a block
When suggestion mode (track changes) is on, block-level AI replacements are blocked so that AI edits are not mis-tracked as suggestions. Turn off suggestion mode to let AI apply changes directly, or accept or reject the pending suggestions first.
Plan limits and tier gates
A button is disabled or a feature says it needs a higher tier
Some features are gated to the Team or Enterprise tier. During beta, usage limits (topics, sites, members) are not enforced, but tier-gated capabilities still follow your project's tier. Request Team or Enterprise access from Settings > Billing. See Plans and limits for what each tier includes.
I cannot add more team members
Adding a member requires the person to already have a Topicary account. You enter their account email, and they are added to the project. There is no sign-up invitation email. Only admins and the project owner can add or remove members.
I do not see analytics
Analytics are available on every tier, including Solo (free). If you do not see reader data, make sure you have at least one published site and that it has received reader traffic. Data can take a few days of activity to appear.
The AI chat widget is not showing on my published site
The reader AI features (embed chat widget, AI search, and the Ask endpoint) are available on every tier, including Solo. If the widget is missing, confirm the target is published and that the embed script tag or widget is configured for the site.
Maps and versions
I cannot delete a map version
The original (root) version cannot be deleted. Only versions created after the original can be removed.
I deleted a version and lost my publication targets
Deleting a map version permanently removes all publication targets associated with it. This action cannot be undone. To preserve published sites, unpublish targets before deleting the version.
Account
How do I reset my password?
Go to the login page and click "Forgot password." Enter your email address to receive a reset link.
Why did search return no results on my published site?
Search indexes topic titles and body text. Try shorter or broader queries. Check for typos. If readers consistently search for terms that return nothing, the content gaps dashboard highlights these zero-result queries so you can create or rename topics to match.
See also
Publish a web site: publishing workflow referenced in several troubleshooting scenarios
Import formats: supported formats and known limitations when importing content
Plans and limits: plan-related limits that cause many of the issues listed above
Content health indicators: automated checks that can surface broken references and undefined variables before publishing