Troubleshooting Guide

June 12, 2026 · View on GitHub

This guide covers common issues and solutions for comment-tasks.nvim.

Configuration Issues

"Provider is disabled" Error

Problem: Provider commands are not available or return "disabled" error.

Solutions:

Check provider configuration:

-- Ensure enabled = true
providers = {
    clickup = {
        enabled = true,  -- ← Must be true
        -- ... other config
    }
}

Verify required fields:

-- Each provider needs specific required fields
clickup = {
    enabled = true,
    api_key_env = "CLICKUP_API_KEY",
    list_id = "123456789",  -- ← Required for ClickUp
    -- ... status configuration
}

Check debug output:

:lua print(vim.inspect(require("comment-tasks.core.config").get_config()))

"API key not found in environment variable" Error

Problem: Plugin can't find your API key in environment variables.

Solutions:

Verify environment variable is set:

echo $CLICKUP_API_KEY
echo $GITHUB_TOKEN
# Should output your API key, not empty

Set environment variable properly:

# In your shell profile (.bashrc, .zshrc, etc.)
export CLICKUP_API_KEY="your_api_key_here"

# Reload your shell or restart Neovim
source ~/.zshrc

Check environment variable name:

-- Ensure api_key_env matches your actual env var name
clickup = {
    api_key_env = "CLICKUP_API_KEY",  -- ← Must match exactly
}

Test in Neovim:
```
:lua print(vim.env.CLICKUP_API_KEY)
```

"Required field not configured" Error

Problem: Missing required configuration fields for your provider.

Solutions:

ClickUp:

clickup = {
    enabled = true,
    api_key_env = "CLICKUP_API_KEY",
    list_id = "123456789",  -- ← Required
    -- team_id is optional
}

GitHub:

github = {
    enabled = true,
    api_key_env = "GITHUB_TOKEN", 
    repo_owner = "username",    -- ← Required
    repo_name = "repository",   -- ← Required
}

Asana:

asana = {
    enabled = true,
    api_key_env = "ASANA_ACCESS_TOKEN",
    project_gid = "1234567890",  -- ← Required
}

API and Connection Issues

"Status not found" or "Invalid transition" Error

Problem: Status names in your configuration don't match the provider's actual statuses.

Solutions:

Check available statuses in your provider:

ClickUp:

curl -H "Authorization: YOUR_API_KEY" \
     "https://api.clickup.com/api/v2/list/LIST_ID"

Asana:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.asana.com/api/1.0/projects/PROJECT_GID"

Update configuration to match exactly:

-- Status names are case-sensitive and must match exactly
statuses = {
    new = "To Do",           -- ← Must match ClickUp status exactly
    completed = "Complete",  -- ← Must match ClickUp status exactly
}

Use provider's web interface to verify status names

Authentication Errors (401/403)

Problem: API requests are being rejected due to authentication issues.

Solutions:

Verify API key is valid:
- Check if key has expired
- Regenerate key if necessary
- Ensure key has correct permissions
Check API key permissions:

GitHub: Needs repo scope for private repos, public_repo for public

ClickUp: Needs access to the specific workspace and list

Asana: Needs access to the project and workspace

Test API key manually:

# GitHub
curl -H "Authorization: token YOUR_TOKEN" \
     "https://api.github.com/user"

# ClickUp  
curl -H "Authorization: YOUR_API_KEY" \
     "https://api.clickup.com/api/v2/user"

Rate Limit Errors (429)

Problem: Too many API requests in a short time period.

Solutions:

Wait for rate limit reset (usually 1 hour)
Reduce request frequency:
- Avoid rapid successive task updates
- Use bulk operations when available (ClickUp)
Check rate limits:
- GitHub: 5,000/hour for authenticated requests
- ClickUp: 100/minute
- Asana: 1,500/hour

Comment Detection Issues

"No comment found on current line" Error

Problem: Plugin can't detect a comment on the current line.

Solutions:

Position cursor correctly:

# TODO: Fix this issue  ← Cursor should be on this line
def my_function():
    pass

Check language detection:

:set filetype?
" Should show correct filetype (python, javascript, etc.)

Force language detection:

:ClickUpTask new python    " Force treat as Python comment
:GitHubTask new javascript " Force treat as JavaScript comment

Verify comment syntax:

# This is detected ✅
## This is detected ✅  
# TODO: This is detected ✅

This is not a comment ❌

Comments Not Being Detected in Specific Languages

Problem: Comments work in some files but not others.

Solutions:

Check supported languages:
- Python: #
- JavaScript/TypeScript: //, /* */
- Lua: --, --[[ ]]
- Rust: //, /* */
- And 10+ more languages

Override language detection:

-- In configuration
languages = {
    custom_lang = {
        comment_nodes = { "comment" },
        comment_styles = {
            single_line = { prefix = "%% ", continue_with = "%% " },
            block = {
                start_markers = { "%{" },
                end_markers = { "%}" },
                continue_with = "",
            },
        },
    }
}

Check Tree-sitter support:
```
:TSInstall python javascript lua rust
```

Command Issues

Commands Not Available

Problem: :ClickUpTask, :GitHubTask etc. commands don't exist.

Solutions:

Check if plugin is loaded:

:lua print(require("comment-tasks"))
" Should not error

Verify provider is enabled and configured:

:lua print(vim.inspect(require("comment-tasks.core.config").get_enabled_providers()))

Check for configuration errors:

" Look for error messages during startup
:messages

Restart Neovim after configuration changes

Dynamic Commands Missing

Problem: Custom status commands (e.g., :ClickUpTask review) are not available.

Solutions:

Check status configuration:

statuses = {
    new = "To Do",
    completed = "Complete", 
    review = "Code Review",  -- ← Creates :ClickUpTask review
}

Verify status names are valid:
- No spaces in status keys
- Use underscores: in_progress not in progress
- Must be valid Vim command names

Check command completion:

:ClickUpTask <Tab>
" Should show your configured statuses

File Reference Issues

File References Not Being Added

Problem: :addfile command doesn't add file references to tasks.

Solutions:

Check if provider supports file references:
- ✅ All providers support basic file references
- ✅ ClickUp has advanced SourceFiles field support

Verify file path:

:pwd  " Check current working directory
:echo expand('%:p')  " Check full file path

Note: addfile always adds the current buffer's file; its only optional argument is a language override:
```
:ClickUpTask addfile python
```

Provider-Specific Issues

ClickUp Issues

List ID Problems:

# Get list ID from URL or API
curl -H "Authorization: YOUR_API_KEY" \
     "https://api.clickup.com/api/v2/team/TEAM_ID/space"

Custom Field Issues:

Ensure SourceFiles field exists in your ClickUp list
Field must be text or URL type
Check field permissions

GitHub Issues

Repository Access:

# Test repository access
curl -H "Authorization: token YOUR_TOKEN" \
     "https://api.github.com/repos/OWNER/REPO"

Token Scopes:

Public repos: public_repo
Private repos: repo
Organizations: May need additional permissions

Asana Issues

Project Access:

# Verify project access
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.asana.com/api/1.0/projects/PROJECT_GID"

Workspace Permissions:

Ensure you're a member of the workspace
Check if project is archived or deleted

Debug Commands

Check Configuration

" View full configuration
:lua print(vim.inspect(require("comment-tasks.core.config").get_config()))

" Check specific provider
:lua print(vim.inspect(require("comment-tasks.core.config").get_provider_config("clickup")))

" View enabled providers
:lua print(vim.inspect(require("comment-tasks.core.config").get_enabled_providers()))

Test Provider Connections

" Test environment variables
:lua print(vim.env.CLICKUP_API_KEY)
:lua print(vim.env.GITHUB_TOKEN)

" Validate the whole configuration (returns warnings/errors)
:lua print(vim.inspect(require("comment-tasks.core.config").validate_config()))

Configuration warnings are also emitted via vim.notify during setup() — check :messages after startup.

Getting Help

Information to Include in Bug Reports

Neovim version: :version
Plugin version: Latest commit or release tag
Configuration: Your setup() call (remove API keys!)
Error messages: Full error output
Environment: OS, shell, environment variables (names only)
Steps to reproduce: Exact steps that cause the issue

Debug Information Commands

" System information
:version
:checkhealth

" Plugin information
:lua print(vim.inspect(require("comment-tasks.core.config").get_config()))

" Environment check (safe - doesn't show values)
:lua for k,v in pairs(vim.env) do if k:match("API") or k:match("TOKEN") then print(k .. "=" .. (v and "SET" or "UNSET")) end end

Common Solutions Checklist

Before asking for help, verify:

Environment variables are set correctly
Provider configuration includes all required fields
API keys have correct permissions
Status names match provider exactly (case-sensitive)
Plugin is loaded without errors (:messages)
Commands are available (tab completion works)
Comment detection works (cursor on comment line)

Support Channels

GitHub Issues: Bug reports and feature requests
GitHub Discussions: Questions and community help
Documentation: Check the README and the other guides in docs/ for details

Remember to remove API keys and sensitive information before sharing configuration!