abpframework/abp · error · CliUsageException

Tool definitions have not been loaded yet. This is an intern

Error message

Tool definitions have not been loaded yet. This is an internal error.

What it means

Thrown by McpHttpClientService.CallToolAsync when _toolDefinitionsLoaded is false, meaning neither InitializeToolNames (loading from cache via McpToolsCacheService) nor GetToolDefinitionsAsync (fetching from ABP.IO server) has been successfully called before a tool invocation request arrived. This is an internal state error: the MCP server accepted a tool call request before completing its startup initialization phase.

Source

Thrown at framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Commands/Services/McpHttpClientService.cs:55

        _logger = logger;
        _mcpLogger = mcpLogger;
        _cachedServerUrlLazy = new Lazy<Task<string>>(GetMcpServerUrlInternalAsync);
    }

    public void InitializeToolNames(List<McpToolDefinition> tools)
    {
        _validToolNames = tools.Select(t => t.Name).ToList();
        _toolDefinitionsLoaded = true;
        _mcpLogger.Debug(LogSource, $"Initialized tool names from cache. Count={tools.Count}, Instance={GetHashCode()}");
    }

    public async Task<string> CallToolAsync(string toolName, JsonElement arguments)
    {
        _mcpLogger.Debug(LogSource, $"CallToolAsync called for '{toolName}'. _toolDefinitionsLoaded={_toolDefinitionsLoaded}, Instance={GetHashCode()}");
        
        if (!_toolDefinitionsLoaded)
        {
            throw new CliUsageException("Tool definitions have not been loaded yet. This is an internal error.");
        }
        
        // Validate toolName against whitelist to prevent malicious input
        if (_validToolNames != null && !_validToolNames.Contains(toolName))
        {
            _mcpLogger.Warning(LogSource, $"Attempted to call unknown tool: {toolName}");
            return CreateErrorResponse($"Unknown tool: {toolName}");
        }

        var baseUrl = await GetMcpServerUrlAsync();
        var url = $"{baseUrl}/tools/call";

        try
        {
            using var httpClient = _httpClientFactory.CreateClient(needsAuthentication: true);

            var jsonContent = JsonSerializer.Serialize(
                new { name = toolName, arguments },

View on GitHub (pinned to 7ed43b1931)

Solutions

1. Restart the ABP MCP server to re-trigger the initialization sequence
2. Delete the MCP tools cache file at CliPaths.McpToolsCache and restart
3. Verify network connectivity to the ABP.IO MCP server URL (check CliPaths.McpConfig for custom URL)
4. Run 'abp login' to ensure authentication is valid before starting the MCP server

// Before calling CallToolAsync, ensure tool definitions are loaded
if (!_mcpHttpClient.AreToolDefinitionsLoaded())
{
    var tools = await _mcpToolsCacheService.GetToolDefinitionsAsync();
    _mcpHttpClient.InitializeToolNames(tools);
}
// Now safe to call tools

try
{
    var result = await _mcpHttpClient.CallToolAsync(toolName, arguments);
}
catch (CliUsageException ex) when (ex.Message.Contains("Tool definitions have not been loaded"))
{
    // Re-initialize and retry once
    var tools = await _mcpToolsCacheService.GetToolDefinitionsAsync();
    _mcpHttpClient.InitializeToolNames(tools);
    result = await _mcpHttpClient.CallToolAsync(toolName, arguments);
}

When it happens

Trigger: A tool call request reaches CallToolAsync before McpToolsCacheService.GetToolDefinitionsAsync has run during MCP server startup. This can happen if cache validation fails (IsCacheValidAsync returns false), the server fetch hasn't completed yet (race condition), or the server fetch returned an empty list causing GetToolDefinitionsAsync in the cache service to throw before InitializeToolNames was called.

Common situations: Race condition during MCP server startup (concurrent tool call before initialization completes), corrupted cache file that fails to deserialize, previous failed server fetch that didn't set the flag, or a DI lifecycle issue where the singleton McpHttpClientService instance wasn't initialized.

Related errors

• Failed to fetch tool definitions from ABP.IO MCP Server. No
• Failed to fetch tool definitions: {errorMessage}
• The following background job(s) are configured for more than
• The distributed lock name '{configuration.LockName}' is used
• No background job is registered for the args type '{argsType

AI-assisted analysis of abpframework/abp@7ed43b1931 (2026-08-13). Data as JSON: /api/errors/3c28077f2c9d12be. Report an issue: GitHub.