microsoft/aspire · error · InvalidOperationException

Project ' ' does not have a valid connection string.

Error message

Project '{project.Name}' does not have a valid connection string.

What it means

During deployment, AzureHostedAgentResource.DeployAsync reads the linked Azure AI Foundry project's endpoint and requires it to be a valid, non-empty connection string. The library throws this error when the project resource's Endpoint resolves to null or empty, because the AIProjectClient cannot be constructed without a project endpoint URL.

Solutions

Ensure the AI Foundry project resource is provisioned before the hosted agent's endpoint value is read (await deployment of the environment first)
Verify the project resource's Endpoint/connection string expression is wired to the deployment output that contains the endpoint URL
Check the provisioning log for errors indicating the Foundry project endpoint output was not produced
Validate locally that project.Endpoint resolves to an https URL of the form https://<resource>.services.ai.azure.com/api/projects/<project>

Example fix

// before
var agent = builder.AddHostedAgent("agent") // project endpoint never populated
    .WithProject(project);
// after
var project = builder.AddAzureCognitiveServicesProject("foundry-project") // provisioned, endpoint output set
    ...
var agent = builder.AddHostedAgent("agent")
    .WithProject(project);

Defensive patterns

Strategy: validation

Validate before calling

var endpoint = await project.Endpoint.GetValueAsync(ct);
if (string.IsNullOrWhiteSpace(endpoint))
    throw new InvalidOperationException($"Project '{project.Name}' endpoint is not set; ensure the Foundry project is provisioned before deploying hosted agents.");

Try / catch

try
{
    await resource.DeployAsync(context);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("does not have a valid connection string"))
{
    logger.LogError(ex, "Foundry project endpoint missing; verify provisioning completed.");
    throw;
}

Prevention

Always provision the AI Foundry project environment before deploying hosted agents
Assert project.Endpoint resolves to an https URL in a pre-deployment check
Log the resolved endpoint early to catch empty values before deployment

When it happens

Trigger: Deploying an app whose AzureCognitiveServicesProjectResource endpoint expression yields an empty value — e.g. the project endpoint output was never assigned during provisioning, or the endpoint callback returned an empty string.

Common situations: Provisioning failed or was skipped so the project endpoint output was never populated; the hosted agent references a project resource whose endpoint was not configured; publishing without running the provisioning step that sets the endpoint.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/a639f7fbbef9479b. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs:163

    }

    /// <summary>
    /// Deploys the specified agent to the given Microsoft Foundry project.
    /// </summary>
    private async Task<ProjectsAgentVersion> DeployAsync(PipelineStepContext context, AzureCognitiveServicesProjectResource project)
    {
        ArgumentNullException.ThrowIfNull(project);

        var azureEnvironment = context.Model.Resources.OfType<AzureEnvironmentResource>().FirstOrDefault() ??
            throw new InvalidOperationException("AzureEnvironmentResource must be present in the application model.");

        var provisioningContext = await azureEnvironment.ProvisioningContextTask.Task.ConfigureAwait(false);
        var credential = provisioningContext.Credential;

        var projectEndpoint = await project.Endpoint.GetValueAsync(context.CancellationToken).ConfigureAwait(false);
        if (string.IsNullOrEmpty(projectEndpoint))
        {
            throw new InvalidOperationException($"Project '{project.Name}' does not have a valid connection string.");
        }
        var def = await ToHostedAgentConfigurationAsync(context).ConfigureAwait(false);
        var options = def.ToProjectsAgentVersionCreationOptions(Target.Name);

        var projectClient = new AIProjectClient(new Uri(projectEndpoint), credential);
        var result = await projectClient.AgentAdministrationClient.CreateAgentVersionAsync(
            Name,
            options,
            cancellationToken: context.CancellationToken
        ).ConfigureAwait(false);

        await UpdateAgentEndpointProtocolsAsync(projectClient.AgentAdministrationClient, def, context.CancellationToken).ConfigureAwait(false);

        // Foundry should do this automatically in the future.
        await AssignFoundryRoleToAgentIdentityAsync(context, project, result.Value, provisioningContext).ConfigureAwait(false);

        return result.Value;
    }

View on GitHub (pinned to 25830f84bd)