Troubleshooting

Common Issues

1. Permission Denied

Problem: The action fails with permission errors.

Solutions:

• Make sure your Notion integration has access to the target page
• Check that the integration is added to the correct workspace
• Verify the page URL is correct and accessible

2. Invalid API Key

Problem: Authentication fails with invalid API key errors.

Solutions:

• Verify your NOTION_API_KEY secret is correct
• Check for extra spaces or characters in the secret value
• Ensure the API key hasn't expired
• Test the API key locally using the CLI

3. Page Not Found

Problem: The action can't find the specified Notion page.

Solutions:

• Check that your NOTION_DOCS_PAGE_URL is valid and accessible
• Ensure the page hasn't been deleted or moved
• Verify the integration has access to the page
• Test the page URL in your browser

4. Build Failures

Problem: The workflow fails during the build process.

Solutions:

• Ensure your repository has the necessary files and structure
• Check that the input path exists and contains valid markdown files
• Verify file permissions and repository structure
• Test the sync locally first

5. Clean Sync Issues

Problem: Clean sync removes more content than expected.

Solutions:

• Use clean sync only on dedicated pages
• Always backup important content before using clean sync
• Test with preview first to understand what will be removed
• Consider using incremental sync instead

Debug Steps

1. Check GitHub Actions Logs

Always start by examining the detailed logs in your GitHub Actions run:

1. Go to your repository's Actions tab
2. Click on the failed workflow run
3. Expand the step that failed
4. Look for specific error messages

2. Verify Secrets

Double-check your repository secrets:

1. Go to Settings → Secrets and variables → Actions
2. Verify secret names match exactly (case-sensitive)
3. Check that secret values don't have extra spaces
4. Test secrets locally if possible

3. Test Locally First

Use the Mk Notes CLI to test your configuration:

# Test with preview
npx mk-notes preview ./docs --format plainText

# Test with sync (be careful!)
npx mk-notes sync ./docs --destination "your-page-url" --api-key "your-key"

4. Use Preview Action

Always use the preview action to verify structure before syncing:

- name: Preview synchronization
  uses: Myastr0/mk-notes/preview
  with:
    input: './docs'
    format: 'plainText'
    output: './preview.txt'

- name: Upload preview for review
  uses: actions/upload-artifact@v4
  with:
    name: sync-preview
    path: ./preview.txt

5. Check Notion Integration

Verify your Notion integration setup:

1. Go to Notion Integrations
2. Check that your integration is active
3. Verify it has access to the correct workspace
4. Ensure the target page is shared with the integration

Getting Help

If you're still experiencing issues:

1. Check the documentation: Review the CLI Commands documentation
2. Search existing issues: Look through our GitHub repository issues
3. Create a new issue: If you can't find a solution, create a new issue with:
   • Detailed error messages
   • Your workflow configuration
   • Steps to reproduce the issue
   • Any relevant logs (remove sensitive information)

Prevention Tips

• Always test workflows in a development environment first
• Use preview actions before syncing
• Keep backups of important Notion content
• Monitor workflow runs regularly
• Use conditional logic to prevent accidental syncs
• Document your workflow configurations

Need help?

If you need help, you can ask for support on the GitHub repository or join our Discord server.