Skip to content

Troubleshooting

Common issues and solutions for mkdocs-to-confluence.

Authentication Issues

Authentication Failed

Symptoms: - 401 Unauthorized error - Authentication failed message

Solutions:

  1. Verify Credentials 

    # Check environment variables
echo $JIRA_USERNAME
echo $CONFLUENCE_API_TOKEN

  2. Check Username Format

  3. Confluence Cloud: Use email address (e.g., user@example.com)

  4. Confluence Server: Use username (e.g., jsmith)

  5. Verify API Token

  6. Generate new token at https://id.atlassian.com/manage-profile/security/api-tokens
  7. Ensure token hasn't expired

  8. Check token has correct permissions

  9. Test Authentication 

    curl -u "email@example.com:api-token" \
  https://your-domain.atlassian.net/wiki/rest/api/space

API Token Not Working

Issue: Token authentication fails

Solutions:

  1. Use HTTP Basic Auth with API token: 

    plugins:
  - mkdocs-to-confluence:
      auth_type: basic  # Not 'bearer'
      username: email@example.com
      api_token: your-token

  2. Check auth_type setting:

  3. basic - For API tokens (default)
  4. bearer - For OAuth tokens only

Connection Issues

Cannot Connect to Confluence

Symptoms: - DNS resolution failed - Connection refused - Network timeout

Solutions:

  1. Verify URL Format 

    # Correct format for Confluence Cloud:
host_url: https://your-domain.atlassian.net/wiki/rest/api/content

# Not:
host_url: https://your-domain.atlassian.net  # ❌ Missing path

  2. Check Network Access 

    # Test connectivity
curl https://your-domain.atlassian.net/wiki/rest/api/space

  3. Firewall/VPN Issues

  4. Check if VPN is required
  5. Verify firewall allows HTTPS (443)

  6. Test from same network as CI/CD

  7. Proxy Configuration 

    export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port

Space and Page Issues

Space Not Found

Symptoms: - Space 'XXX' not found - 404 Not Found error

Solutions:

  1. Verify Space Key
  2. Space key is case-sensitive
  3. Find in URL: https://.../wiki/spaces/SPACEKEY/

  4. Or in Confluence: Space Settings → Overview

  5. Check Permissions 

    # Test space access
curl -u "email:token" \
  https://your-domain.atlassian.net/wiki/rest/api/space/SPACEKEY

  6. Verify Account Access

  7. Log into Confluence web UI
  8. Navigate to the space
  9. Confirm you can view/edit pages

Parent Page Not Found

Symptoms: - Parent page 'Title' not found - Pages created at wrong location

Solutions:

  1. Create Parent Page First
  2. Manually create parent page in Confluence

  3. Or set parent_page_name to existing page

  4. Verify Exact Title 

    # Title must match exactly (case-sensitive)
parent_page_name: "API Documentation"  # Not "api documentation"

  5. Check Page Permissions

  6. Ensure you can edit the parent page

  7. Verify page isn't restricted

  8. Use Space as Parent 

    # Omit parent_page_name to use space root
plugins:
  - mkdocs-to-confluence:
      space: DOCS
      # No parent_page_name - creates at space root

Page Already Exists

Symptoms: - Duplicate pages created - "Page with this title already exists" error

Solutions:

  1. Check for Duplicates
  2. Search Confluence for existing page
  3. Delete duplicates manually

  4. Ensure unique page titles

  5. Review Navigation 

    nav:
  - Getting Started: start.md
  - Getting Started: intro.md  # ❌ Duplicate title

  6. Enable Debug Mode 

    debug: true
    Check logs for page ID resolution

Image and Attachment Issues

Images Not Uploading

Symptoms: - Images missing in Confluence - Broken image links

Solutions:

  1. Verify Image Paths 

    # Correct - relative to docs/
![Diagram](images/diagram.png)

# Incorrect - absolute path
![Diagram](/absolute/path/diagram.png)  # ❌

  2. Check File Exists 

    ls docs/images/diagram.png

  3. Supported Formats

  4. PNG, JPG, JPEG, GIF
  5. SVG (check Confluence version)

  6. PDF (as attachments)

  7. File Size Limits

  8. Confluence has file size limits (typically 100MB)

  9. Compress large images

  10. Debug Attachment Process 

    debug: true
    Look for attachment upload messages

Attachments Not Updating

Symptoms: - Old image versions in Confluence - Changes not reflected

Solutions:

  1. Check Hash Updates
  2. Plugin uses SHA1 hash to track changes

  3. Look for log: Attachment: file.png - *UPDATE*

  4. Clear Confluence Cache

  5. Confluence may cache images

  6. Hard refresh browser (Ctrl+F5)

  7. Force Re-upload

  8. Delete attachment in Confluence
  9. Rebuild documentation

Build and Sync Issues

Pages Not Syncing

Symptoms: - Build succeeds but pages missing - No changes in Confluence

Solutions:

  1. Check Plugin Enabled 

    plugins:
  - search
  - mkdocs-to-confluence:  # Must be listed

  2. Verify Environment Variable 

    enabled_if_env: PUBLISH_TO_CONFLUENCE

    # Check it's set
echo $PUBLISH_TO_CONFLUENCE  # Should be "1"

  3. Check Dry Run Mode 

    dryrun: false  # Must be false to publish

  4. Review Build Logs 

    mkdocs build --verbose

Content Not Updating

Symptoms: - Build shows *NO CHANGE* - Content appears different

Solutions:

  1. Check Normalized Comparison
  2. Plugin normalizes content before comparison

  3. Enable debug_diff mode to see content comparison: 

    debug_diff: true  # Shows detailed content comparison and creates diff files

  4. Review Debug Files 

    ls /tmp/confluence-debug/
diff /tmp/confluence-debug/Page_current_normalized.html \
     /tmp/confluence-debug/Page_new_normalized.html

  5. Force Update

  6. Delete page in Confluence
  7. Rebuild documentation

Build Hangs or Times Out

Symptoms: - Build process hangs - Timeout errors

Solutions:

  1. Check Rate Limiting
  2. Confluence may rate-limit API calls

  3. Add delays between requests

  4. Reduce Page Count

  5. Build smaller sets of pages

  6. Use conditional publishing

  7. Check Network Stability

  8. Verify consistent connectivity

  9. Test with smaller builds

  10. Increase Timeout 

    # Custom timeout in plugin (advanced)
timeout=300  # 5 minutes

Permission Issues

Permission Denied

Symptoms: - 403 Forbidden error - "You don't have permission" message

Solutions:

  1. Verify Space Permissions
  2. Log into Confluence
  3. Navigate to Space Settings → Permissions

  4. Ensure account has "Add Pages" permission

  5. Check Page Restrictions

  6. Parent page may have restrictions
  7. View page → Restrictions

  8. Add your account to allowed users/groups

  9. Admin Rights

  10. Some operations require admin rights

  11. Contact Confluence administrator

  12. API Token Scope

  13. Ensure token has write permissions
  14. Regenerate token with correct scopes

Debugging Strategies

Enable Debug Logging

plugins:
  - mkdocs-to-confluence:
      debug: true        # General debug info (API calls, parent chain, etc.)
      debug_diff: true   # Detailed content comparison (creates temp files)
      verbose: true

Output includes: - debug: API request/response details, parent chain resolution, attachment processing - debug_diff: Content comparison details, normalized diff files, character counts

Use Dry Run Mode

plugins:
  - mkdocs-to-confluence:
      dryrun: true
      export_dir: confluence-export

Benefits: - Preview converted HTML - Verify page hierarchy - Check attachment paths - Test without publishing

Check Debug Files

# Content comparison
ls /tmp/confluence-debug/

# View normalized content
cat /tmp/confluence-debug/Page_Title_current_normalized.html
cat /tmp/confluence-debug/Page_Title_new_normalized.html

# Compare
diff /tmp/confluence-debug/Page_Title_current_normalized.html \
     /tmp/confluence-debug/Page_Title_new_normalized.html

Test API Access

# Test authentication
curl -u "email:token" \
  https://your-domain.atlassian.net/wiki/rest/api/space

# Test space access
curl -u "email:token" \
  https://your-domain.atlassian.net/wiki/rest/api/space/SPACEKEY

# Test page creation
curl -u "email:token" -X POST \
  -H "Content-Type: application/json" \
  -d '{"type":"page","title":"Test","space":{"key":"SPACEKEY"},"body":{"storage":{"value":"<p>Test</p>","representation":"storage"}}}' \
  https://your-domain.atlassian.net/wiki/rest/api/content

Getting Help

If you're still stuck:

  1. Check Logs Carefully
  2. Enable debug mode
  3. Look for specific error messages

  4. Note line numbers and context

  5. Search Existing Issues

  6. GitHub Issues

  7. Check closed issues too

  8. Create Minimal Reproduction

  9. Simplify configuration
  10. Test with minimal docs

  11. Isolate the problem

  12. Report Issue

  13. Include configuration (redact credentials!)
  14. Include error messages
  15. Include debug output
  16. Include MkDocs/Python versions

Common Error Messages

"YOU HAVE EMPTY VALUES IN YOUR CONFIG"

Cause: Required configuration parameters missing

Solution: Verify all required fields: 

host_url: <must be set>
space: <must be set>
username: <must be set or env var>
api_token: <must be set or env var>

"ROOT PARENT 'XXX' UNKNOWN. ABORTING!"

Cause: Parent page specified in config doesn't exist

Solution: - Create the parent page in Confluence first - Or remove parent_page_name to use space root

"PAGE DOES NOT EXIST YET!"

Cause: Trying to update non-existent page (internal error)

Solution: Should auto-create. If persistent, report bug.

"HTTP error on adding page"

Cause: Parent page not yet synced to Confluence

Solution: Plugin will retry automatically. If fails, check logs.

Next Steps