{"record":{"id":"c21984b7c0b4761d","repo":"spring-projects/spring-boot","slug":"docker-api-call-to-failed-with-status-code","errorCode":null,"errorMessage":"Docker API call to '{}' failed with status code {}","messagePattern":"Docker API call to '(.+?)' failed with status code (.+?)","errorType":"http","errorClass":"DockerEngineException","httpStatus":null,"severity":"error","filePath":"buildpack/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/transport/HttpClientTransport.java","lineNumber":170,"sourceCode":"\n\tprivate Response execute(HttpUriRequestBase request, @Nullable String registryAuth) {\n\t\tif (StringUtils.hasText(registryAuth)) {\n\t\t\trequest.setHeader(REGISTRY_AUTH_HEADER, registryAuth);\n\t\t}\n\t\treturn execute(request);\n\t}\n\n\tprivate Response execute(HttpUriRequest request) {\n\t\ttry {\n\t\t\tbeforeExecute(request);\n\t\t\tClassicHttpResponse response = this.client.executeOpen(this.host, request, null);\n\t\t\tint statusCode = response.getCode();\n\t\t\tif (statusCode >= 400 && statusCode <= 500) {\n\t\t\t\tbyte[] content = readContent(response);\n\t\t\t\tresponse.close();\n\t\t\t\tErrors errors = (statusCode != 500) ? deserializeErrors(content) : null;\n\t\t\t\tMessage message = deserializeMessage(content);\n\t\t\t\tthrow new DockerEngineException(this.host.toHostString(), request.getUri(), statusCode,\n\t\t\t\t\t\tresponse.getReasonPhrase(), errors, message, content);\n\t\t\t}\n\t\t\treturn new HttpClientResponse(response);\n\t\t}\n\t\tcatch (IOException | URISyntaxException ex) {\n\t\t\tthrow new DockerConnectionException(this.host.toHostString(), ex);\n\t\t}\n\t}\n\n\tprotected void beforeExecute(HttpRequest request) {\n\t}\n\n\tprivate byte @Nullable [] readContent(ClassicHttpResponse response) throws IOException {\n\t\tHttpEntity entity = response.getEntity();\n\t\tif (entity == null) {\n\t\t\treturn null;\n\t\t}\n\t\ttry (InputStream stream = entity.getContent()) {","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/spring-projects/spring-boot/blob/270dfe353fb830fd69b823a8a859287ff103854b/buildpack/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/transport/HttpClientTransport.java#L152-L188","documentation":"HttpClientTransport.execute saw an HTTP status in [400, 500] inclusive from the Docker daemon and threw DockerEngineException. The message is built by DockerEngineException.buildMessage: 'Docker API call to <host><uri> failed with status code <code>' plus optional reason phrase, response message, and structured Errors from the body. For status 500 the Errors deserialization is skipped (only Message is parsed). This is the umbrella exception for any Docker API request that the daemon rejected.","triggerScenarios":"Any of get/post/put/delete/head routes through execute (line 160); client.executeOpen returns a ClassicHttpResponse whose getCode() is >= 400 and <= 500. Examples: 404 pulling a builder/base image that does not exist; 401 pushing to a registry without credentials; 400 malformed reference/builder name; 500 daemon-side build failure.","commonSituations":"Referencing a builder image (docker.io/paketobuildpacks/builder:base) or run image that does not exist or is not accessible; pushing to a registry while unauthenticated; builder image incompatible with the daemon version; daemon disk full; reference/tag typo.","solutions":["Read the structured detail from the exception: getStatusCode(), getReasonPhrase(), getErrors(), getResponseMessage() — the daemon's explanation is there.","For 404, verify image and builder names and that the daemon can reach the registry (`docker pull <image>`).","For 401/403, configure registry auth (`docker login`) so the buildpack can read config.json credentials.","For 500, inspect `docker daemon` logs / `journalctl -u docker` for the server-side error."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Best-effort pre-checks: validate image references exist via `docker manifest inspect`\nProcess p = new ProcessBuilder(\"docker\", \"manifest\", \"inspect\", imageRef)\n        .redirectErrorStream(true).start();\nif (p.waitFor() != 0) {\n    throw new IllegalArgumentException(\"Image not found or inaccessible: \" + imageRef);\n}","typeGuard":null,"tryCatchPattern":"try {\n    transport.post(uri, auth);\n} catch (DockerEngineException ex) {\n    switch (ex.getStatusCode()) {\n        case 401, 403 -> { /* configure registry auth: docker login */ }\n        case 404      -> { /* verify image/builder reference */ }\n        case 500      -> { /* inspect daemon logs; getResponseMessage()/getErrors() */ }\n        default       -> { /* surface getErrors()/getResponseMessage() */ }\n    }\n    throw ex;\n}","preventionTips":["Pre-validate image and builder references (`docker pull`, `docker manifest inspect`).","Ensure registry credentials are configured (`docker login`) before the buildpack run.","Surface getErrors() and getResponseMessage() in user-facing messages for 4xx/500."],"tags":["docker","api","http","network","buildpack"],"backgroundTag":null,"analyzedSha":"270dfe353fb830fd69b823a8a859287ff103854b","analyzedAt":"2026-08-11T19:42:06.541Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}