Help Center › Troubleshooting

Troubleshooting Guide

Common issues and step-by-step solutions.

Quick Diagnosis

Most generation issues fall into three categories: input quality (the source material lacks enough context), format mismatch (the selected doc type doesn't match the input), or temporary service issues (retry usually resolves these). Start with the relevant section below.

Input
My generated docs have incorrect or placeholder code examples
Typically occurs when the source input (OpenAPI spec or code) has missing or generic descriptions, or when parameter types/examples are not defined in the spec.
  1. Open your OpenAPI spec and check that each endpoint has a non-empty description field. Generic descriptions like "Endpoint for users" produce generic output.
  2. Add example values to your request body properties in the spec — DocCraft uses these to populate code examples.
  3. If using plain text input, explicitly include sample request/response JSON in your description. Example: "The create user endpoint accepts: {name: 'Alice', email: 'alice@example.com', role: 'admin'}"
  4. Regenerate the affected section(s) using the per-section Regenerate button with the instruction: "Generate realistic code examples using the request body schema above."
Input
DocCraft isn't recognizing my API endpoints
This usually means the uploaded OpenAPI spec has structural issues — missing paths object, incorrect YAML indentation, or a spec version DocCraft doesn't fully support.
  1. Validate your spec using the Swagger Editor — paste your spec and check for red errors in the left pane.
  2. Ensure your spec declares openapi: 3.0.x or swagger: "2.0" at the top. DocCraft supports OpenAPI 2.0 and 3.0. OpenAPI 3.1 support is partial.
  3. Check that the paths key is present and each path starts with /. Missing leading slashes on paths cause silent failures.
  4. If your spec is large (>500 endpoints), try splitting it into smaller files and uploading one at a time.
  5. If the issue persists after validation, try exporting a Postman collection from the same API and uploading the .json collection file instead.
Integration
Export to Confluence fails with "Authentication Error"
The most common cause is an expired or incorrectly scoped Confluence API token, or an incorrect workspace URL format.
  1. Go to Settings → Integrations → Confluence and verify your workspace URL is in the format https://yourcompany.atlassian.net — not yourcompany.atlassian.net/wiki or yourcompany.confluence.com.
  2. Regenerate your Confluence API token at id.atlassian.com → Security → API tokens → Create API Token. Tokens can expire or be revoked by your Atlassian admin.
  3. Confirm the account associated with the token has Space Admin or at minimum Add pages permission on the target Confluence Space.
  4. Test your credentials: try the Atlassian REST API directly with curl -u email:token https://yourcompany.atlassian.net/rest/api/content — if this returns a 401, your credentials are incorrect.
  5. After updating credentials in Settings, click Test Connection before attempting another export.
Quality
Generated docs are too generic — missing specific details about my product
DocCraft can only generate documentation based on what is in the source material. If your source lacks product-specific context, the output will be generic.
  1. Add a product context blurb at the top of your input — 2-3 sentences describing what your product does, who uses it, and any key constraints. Example: "PayAPI is a REST API for ACH payment processing targeting US fintech companies. It processes PPD, CCD, and WEB payments with T+1 settlement via the NACHA network."
  2. Expand your OpenAPI spec descriptions — every endpoint, parameter, and response code should have a description. The richer the spec, the more specific the output.
  3. Use Advanced Settings → Custom Instructions to provide style and audience guidance: "Write for developers integrating the API for the first time. Use imperative mood. Include warning callouts for rate limiting."
  4. After generation, use per-section Regenerate to enhance sparse sections individually.
Limits
Rate limit exceeded — "Too many requests" error
Free-tier accounts have generation rate limits in addition to monthly credit limits. Generating multiple documents in quick succession can trigger a short-term rate limit.
  1. Wait 60 seconds and retry the generation. Short-term rate limits usually clear within a minute.
  2. If you're in a batch workflow (generating many documents), add a minimum 30-second delay between requests.
  3. Check your monthly credit balance in Account Settings → Usage. If you've exhausted monthly credits, you'll need to wait for the next reset or upgrade your plan.
  4. For high-volume programmatic use, the DocCraft API (coming 2025) will include configurable rate limits appropriate for automation workflows.
Upload
Cannot upload file — "File too large" error
DocCraft accepts uploaded files up to 5 MB. Large monorepo exports, full Postman workspaces, or bundled specs may exceed this limit.
  1. Split your spec into smaller files. For large OpenAPI specs, separate by tag/domain and generate one documentation set per logical section.
  2. For Postman collections, export individual collections rather than full workspace backups.
  3. For code-based input, create a focused subset of files rather than exporting the entire repo. DocCraft performs best with 3-10 representative files rather than a full codebase.
  4. For GitHub repos: paste only the repository URL instead of uploading a ZIP archive — URL ingestion does not have a file size constraint.
Issue not listed here? Check the FAQ or open a support request from your DocCraft Dashboard → Help → Contact Support.