{"record":{"id":"b7dbfab10b17ba3b","repo":"microsoft/aspire","slug":"imagename-must-be-provided-in-options","errorCode":null,"errorMessage":"ImageName must be provided in options.","messagePattern":"ImageName must be provided in options\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/Publishing/DockerContainerRuntime.cs","lineNumber":26,"sourceCode":"using Aspire.Hosting.Dcp.Process;\nusing Aspire.Shared;\nusing Microsoft.Extensions.Logging;\n\nnamespace Aspire.Hosting.Publishing;\n\ninternal sealed class DockerContainerRuntime : ContainerRuntimeBase<DockerContainerRuntime>\n{\n    public DockerContainerRuntime(ILogger<DockerContainerRuntime> logger, IProcessRunner processRunner) : base(logger, processRunner)\n    {\n    }\n\n    protected override string RuntimeExecutable => KnownContainerRuntimes.Docker;\n    public override string Name => \"Docker\";\n    private async Task RunDockerBuildAsync(string contextPath, string dockerfilePath, ContainerImageBuildOptions? options, Dictionary<string, string?> buildArguments, Dictionary<string, BuildImageSecretValue> buildSecrets, string? stage, CancellationToken cancellationToken)\n    {\n        var imageName = !string.IsNullOrEmpty(options?.Tag)\n            ? $\"{options.ImageName}:{options.Tag}\"\n            : options?.ImageName ?? throw new ArgumentException(\"ImageName must be provided in options.\", nameof(options));\n\n        string? builderName = null;\n        var resourceName = ResourceExtensions.FlattenContainerImageName(imageName);\n\n        // Docker requires a custom buildkit instance for the image when\n        // targeting the OCI format so we construct it and remove it here.\n        if (options?.ImageFormat == ContainerImageFormat.Oci)\n        {\n            if (string.IsNullOrEmpty(options?.OutputPath))\n            {\n                throw new ArgumentException(\"OutputPath must be provided when ImageFormat is Oci.\", nameof(options));\n            }\n\n            builderName = $\"{resourceName}-builder\";\n            await CreateBuildkitInstanceAsync(builderName, cancellationToken).ConfigureAwait(false);\n        }\n\n        try","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/Publishing/DockerContainerRuntime.cs#L8-L44","documentation":"DockerContainerRuntime.BuildImageAsync ultimately needs an image name to tag and build. When the options object is supplied but its ImageName is null or empty (and no Tag alternative exists), RunDockerBuildAsync throws ArgumentException naming the 'options' parameter. This is a defensive guard against callers constructing ContainerImageBuildOptions without the required image name.","triggerScenarios":"Calling BuildImageAsync (via DockerContainerRuntime) with a ContainerImageBuildOptions instance whose ImageName is null/empty — e.g. new ContainerImageBuildOptions { Tag = \"v1\" } without ImageName, since even a Tag produces \"$null:v1\" and falls through to the ImageName check.","commonSituations":"Programmatically building options where the image name comes from a nullable resource property or config value that was not populated; copying sample code and omitting ImageName; refactors that rename the image-name property leaving the assignment dropped.","solutions":["Set ImageName on the ContainerImageBuildOptions before calling BuildImageAsync.","Validate the options object at construction time (required property) so it cannot be created without ImageName.","Check the upstream source of the image name (resource name, config) for null/empty values and fix that."],"exampleFix":"// before\nvar options = new ContainerImageBuildOptions { Tag = \"v1\" };\n// after\nvar options = new ContainerImageBuildOptions { ImageName = \"myapp/api\", Tag = \"v1\" };","handlingStrategy":"validation","validationCode":"if (options is null || string.IsNullOrWhiteSpace(options.ImageName))\n{\n    throw new ArgumentException(\"ImageName must be set before building an image.\", nameof(options));\n}","typeGuard":"bool HasImageName(ContainerImageBuildOptions? o) => !string.IsNullOrWhiteSpace(o?.ImageName);","tryCatchPattern":"try\n{\n    await runtime.BuildImageAsync(ctx, dockerfile, options, args, secrets, stage, ct);\n}\ncatch (ArgumentException ex) when (ex.ParamName == \"options\")\n{\n    logger.LogError(ex, \"Image build options are incomplete: {Message}\", ex.Message);\n}","preventionTips":["Make ImageName required at options construction (checked in factory/constructor).","Centralize option building in one helper that validates required fields.","Resolve the image name from resource metadata before the build call, not inside it."],"tags":["docker","image-build","argument-validation"],"backgroundTag":"missing-required-argument","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T09:17:21.228Z"}