<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>Install Failure on RockB</title><link>https://baeseokjae.github.io/tags/install-failure/</link><description>Recent content in Install Failure on RockB</description><image><title>RockB</title><url>https://baeseokjae.github.io/images/og-default.png</url><link>https://baeseokjae.github.io/images/og-default.png</link></image><generator>Hugo</generator><language>en-us</language><lastBuildDate>Thu, 12 Nov 2026 19:08:00 +0000</lastBuildDate><atom:link href="https://baeseokjae.github.io/tags/install-failure/index.xml" rel="self" type="application/rss+xml"/><item><title>ACP Install Failed: What JetBrains' package_install_failed Log Line Actually Tells You (2026)</title><link>https://baeseokjae.github.io/posts/jetbrains-acp-package-install-failed-diagnosis-2026/</link><pubDate>Thu, 12 Nov 2026 00:00:00 +0000</pubDate><guid>https://baeseokjae.github.io/posts/jetbrains-acp-package-install-failed-diagnosis-2026/</guid><description>The line &amp;#39;Agent installation failed for acp.registry.claude-acp: package_install_failed&amp;#39; names a package and one generic token, not a failing step. Six loopback cases against a stub ACP registry show five distinct server-side signatures that all collapse into that same message, plus an ordered seven-check pre-flight you can run before reinstalling.</description><content:encoded><![CDATA[<p>You clicked Install in the AI Assistant agent list, the agent never appeared in AI Chat, and the log shows one line:</p>
<pre tabindex="0"><code>WARN - #c.i.a.a.r.r.acpagentinstallationstate - Agent installation failed for acp.registry.claude-acp: package_install_failed
</code></pre><p>That line is what a reader pasted into a search engine on 2026-11-06, and it is the entire failure report: a package id, a colon, and a token that says &ldquo;package install failed&rdquo;. It does not say which step failed, what the HTTP status was, or whether anything was downloaded at all.</p>
<p>Here is the direct answer this article can defend. <code>package_install_failed</code> is a single bucket name for the client&rsquo;s installation path, and the documented installation path has seven places that can fail before an agent ever starts a JSON-RPC session: fetching the registry index, finding your agent&rsquo;s entry in it, the entry&rsquo;s schema, selecting a distribution for your platform, downloading the artifact, matching the artifact&rsquo;s SHA-256, and resolving a runtime the entry needs. Every one of those failures can end in the same sentence. The token is not a diagnosis; it is a label on an empty box.</p>
<p>What does narrow it is a check order. This article publishes a runnable pre-flight (<code>acp_install_check.py</code>) and the six-case fixture used to test it, including the one case where the checker must return PASS so you know a clean install does not produce a false alarm.</p>
<h2 id="what-the-string-actually-contains">What the string actually contains</h2>
<p>Three parts, none of them a stage:</p>
<ul>
<li><code>acp.registry.claude-acp</code> — the registry id, <code>claude-acp</code>, prefixed by the source it came from. This tells you the install came from the registry rather than from a hand-written <a href="https://www.jetbrains.com/help/ai-assistant/acp.html"><code>acp.json</code></a>, which is a different code path with a different failure surface.</li>
<li><code>package_install_failed</code> — the bucket. It reads like &ldquo;the package did not install&rdquo;, which is true of every failure in the install path.</li>
<li><code>#c.i.a.a.r.r.acpagentinstallationstate</code> — a client-internal class reference. It is not documented anywhere in JetBrains&rsquo; published help, and this article does not expand the abbreviation. Guessing that <code>a.a.r.r</code> means &ldquo;agent assistant registry resolver&rdquo; would be invention dressed as evidence.</li>
</ul>
<p>The JetBrains help page describes installation as three automatic steps: &ldquo;Downloads the required agent files&rdquo;, &ldquo;Downloads and manages a Node.js or Python runtime if required&rdquo;, and &ldquo;Prepares the agent for use&rdquo; (<a href="https://www.jetbrains.com/help/ai-assistant/acp.html">AI Assistant ACP documentation</a>). Three documented steps, zero documented error taxonomy. A four-word token cannot span them.</p>
<h2 id="the-contract-the-installer-is-actually-reading">The contract the installer is actually reading</h2>
<p>The ACP registry is not a per-agent manifest service. It is one index document whose entries carry their own distribution blocks (<a href="https://raw.githubusercontent.com/agentclientprotocol/registry/main/FORMAT.md">registry FORMAT.md</a>):</p>
<ul>
<li>the index has a <code>version</code> and an <code>agents</code> array;</li>
<li>each entry has <code>id</code>, <code>name</code>, <code>version</code>, <code>description</code>, <code>repository</code>, <code>authors</code>, <code>license</code>, and a required <code>license_url</code> — the format says the field &ldquo;is required and must link to the agent&rsquo;s license text or terms of service&rdquo;, with one named exemption;</li>
<li>each entry has a <code>distribution</code> object with one or more of <code>binary</code> (keyed by platform: <code>darwin-aarch64</code>, <code>linux-x86_64</code>, <code>windows-x86_64</code>, plus <code>-musl</code> variants), <code>npx</code>, and <code>uvx</code>;</li>
<li>each binary target may carry <code>archive</code>, <code>sha256</code>, <code>cmd</code>, <code>args</code>, <code>env</code> — the SHA-256 is documented as an integrity check, and the field is optional;</li>
<li>installer formats such as <code>.dmg</code>, <code>.pkg</code>, <code>.deb</code>, <code>.rpm</code>, <code>.msi</code> are explicitly not supported, only <code>.zip</code>, <code>.tar.gz</code>, <code>.tgz</code>, <code>.tar.bz2</code>, <code>.tbz2</code> or a raw binary.</li>
</ul>
<p>JetBrains IDEs read a dedicated index at <code>cdn.agentclientprotocol.com</code>, not the generic one, and there is a separate preview channel (<a href="https://raw.githubusercontent.com/agentclientprotocol/registry/main/README.md">registry README</a>). The live JetBrains index is a single JSON document, and the entry for <code>claude-acp</code> at version 0.106.0 declares both a per-platform binary with a SHA-256 and an <code>npx</code> fallback (<a href="https://cdn.agentclientprotocol.com/registry/v1/latest/registry-for-jetbrains.json">registry-for-jetbrains.json</a>). The index also carries an <code>environments.node</code> block pinning Node.js 24.22.1 with per-platform hashes — that is the shape of the &ldquo;downloads and manages a Node.js runtime&rdquo; promise, though nobody documents the client actually consuming that block, so treat it as correlation.</p>
<p>The corresponding npm package declares <code>engines.node: &quot;&gt;=22&quot;</code> and a <code>claude-agent-acp</code> bin (<a href="https://registry.npmjs.org/@agentclientprotocol/claude-agent-acp">npm metadata</a>, <a href="https://raw.githubusercontent.com/agentclientprotocol/claude-agent-acp/main/package.json">package.json</a>). The registry README also says every listed agent is CI-verified for <code>authMethods</code> in the ACP handshake, and the launch post says only agents supporting Agent Auth or Terminal Auth are featured (<a href="https://blog.jetbrains.com/ai/2026/01/acp-agent-registry/">JetBrains registry launch</a>). That matters for expectations: an agent passing the auth conformance check is not the same as an agent whose archive exists for your platform.</p>
<p>One correction to our own earlier coverage: <a href="https://baeseokjae.github.io/posts/jetbrains-acp-agent-registry-guide-2026/">our registry guide</a> says that when an agent needs an external binary, &ldquo;the IDE surfaces a clear error message pointing you to the installation page — it does not silently fail.&rdquo; That claim is too generous. Nothing here is silent, but a message that names only a package and a bucket is not the clear pointer the guide promised, and the guide&rsquo;s menu path (&ldquo;Settings → Tools → AI Agents → Registry&rdquo;) no longer matches the current documentation, which places agents under &ldquo;Settings | Tools | AI Assistant | Agents&rdquo;. Both statements are documentation drift, and readers who followed either one deserved better than this log line.</p>
<h2 id="six-cases-one-message">Six cases, one message</h2>
<p>Documentation tells you which fields exist. It cannot tell you which field broke. So the fixture serves the real contract on loopback and breaks it one field at a time.</p>
<p>The stub registry (<code>acp_stub_registry.py</code>) serves exactly two routes: the index at <code>/registry-for-jetbrains.json</code> and artifacts under <code>/artifacts/</code>. It logs every request — method, path, status, bytes, latency — to a JSONL transcript, so the server-side signature of each defect is a record rather than a description. The runner (<code>run_defects.py</code>) builds a fresh fixture per case, binds a fresh ephemeral port, runs the checker once, and stores the transcript beside the checker output.</p>
<p>Environment for the published run: Python 3.12.3, Node.js v24.21.0, npm 11.19.0, Linux 6.17.0 on aarch64, loopback only, no network, no credentials. The checker is told to evaluate <code>linux-x86_64</code> as the target platform and never executes an artifact; nothing in this fixture downloads or runs third-party code. All six cases together took 2.6 seconds of wall clock (recorded as <code>wall_clock_s</code> in <code>results.json</code>). No IDE build is passed to the checker, because there is no JetBrains IDE on the host that produced these records.</p>
<table>
	<thead>
			<tr>
					<th>Case</th>
					<th>What the server actually did</th>
					<th>Failing check</th>
					<th>Exit</th>
					<th>Signature visible in the log line?</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>D0 clean</td>
					<td>200 index (1425 bytes), 200 artifact (208 bytes), hash matches</td>
					<td>none</td>
					<td>0</td>
					<td>n/a — a healthy install is the control</td>
			</tr>
			<tr>
					<td>D1 index 404</td>
					<td>index route returns 404, no agent data ever sent</td>
					<td><code>index_fetch</code></td>
					<td>1</td>
					<td>No. Same bucket.</td>
			</tr>
			<tr>
					<td>D2 entry schema</td>
					<td>index 200, entry present, <code>license_url</code> missing</td>
					<td><code>entry_schema</code></td>
					<td>1</td>
					<td>No. Same bucket.</td>
			</tr>
			<tr>
					<td>D3 checksum</td>
					<td>index 200, artifact 200 (246 bytes), served bytes hash differently</td>
					<td><code>artifact_sha256</code></td>
					<td>1</td>
					<td>No. Same bucket.</td>
			</tr>
			<tr>
					<td>D4 unreachable artifact</td>
					<td>index 200, artifact host refuses the connection; the transcript contains no artifact request at all</td>
					<td><code>artifact_fetch</code></td>
					<td>1</td>
					<td>No. Same bucket.</td>
			</tr>
			<tr>
					<td>D5 platform gap</td>
					<td>index 200, entry declares only <code>darwin-aarch64</code>, no <code>npx</code>/<code>uvx</code> fallback</td>
					<td><code>distribution_select</code></td>
					<td>1</td>
					<td>No. Same bucket.</td>
			</tr>
	</tbody>
</table>
<p>Five injected defects produced five distinct failing checks and zero false passes, and the clean control passed every check that could run on the host. The transcript for D4 is one line long — the index request — because the artifact request never reached a server. That absence is itself a signature: a refused connection leaves no server-side record, which is exactly why an install failure with an empty download log looks the same as a schema rejection.</p>
<p>What the experiment does not show: it does not reproduce the IDE. There is no JetBrains IDE on the machine that produced these records, so the log line is treated as user-reported and the client&rsquo;s internal mapping from failure to message is not claimed. The fixture proves that the contract layer admits five failures that a single token cannot separate. It does not prove what the client prints for each, and it cannot, from the outside.</p>
<h2 id="the-pre-flight-in-order">The pre-flight, in order</h2>
<p>Run these in order and stop at the first FAIL. Each check costs seconds and eliminates whole layers. The script prints PASS, FAIL or SKIP per check and exits non-zero on the first failure, but you can do the first three by hand in a terminal.</p>
<ol>
<li><strong>Index reachability.</strong> <code>curl -sS -o /dev/null -w '%{http_code}\n' https://cdn.agentclientprotocol.com/registry/v1/latest/registry-for-jetbrains.json</code>. A 200 means the client can at least read the catalog. A 403 or 407 means a proxy or egress filter, not an agent problem. A DNS failure means your network path, full stop. If you are on the preview channel, the URL ends <code>-preview.json</code>, and those distributions are documented as not verified for reachability — a preview entry can legitimately point at something that is not there.</li>
<li><strong>Your IDE build.</strong> The registry shipped as beta for IDE versions 2025.3 and later, with a matching AI plugin update (<a href="https://blog.jetbrains.com/ai/2026/01/acp-agent-registry/">launch post</a>). An older build is a plausible cause class and is checkable locally in Help → About. The registry format itself encodes no minimum-IDE field, so no server response will ever tell you this; it is a client-side gate.</li>
<li><strong>Your entry&rsquo;s schema.</strong> Fetch the index and confirm the entry has <code>id</code>, <code>name</code>, <code>version</code>, <code>repository</code>, <code>license_url</code> and <code>distribution</code>. <code>license_url</code> is documented as required. A registry entry can be structurally invalid and still be published for a while, which is why D2 is a real failure mode rather than a hypothetical.</li>
<li><strong>A distribution for your platform.</strong> Look inside <code>distribution.binary</code> for your exact key (<code>linux-x86_64</code> is glibc x86-64; Alpine needs <code>linux-x86_64-musl</code>). The format is explicit that a missing musl target must be treated as unavailable rather than silently substituted with a glibc build. If there is no binary for you, the <code>npx</code> or <code>uvx</code> fallback is the path — and that path has its own runtime requirement.</li>
<li><strong>Artifact reachability.</strong> Take the <code>archive</code> URL from the entry and fetch it. A 404 means the index points at a release that has been withdrawn; the client will report a generic install failure, and the registry is the thing that is wrong. A connection refused, as in D4, means the host is unreachable from your machine only.</li>
<li><strong>Checksum.</strong> <code>sha256sum</code> the downloaded bytes and compare with the entry&rsquo;s <code>sha256</code>. A mismatch is not a corrupted agent; it is bytes that are not the declared release, which in practice means a truncated download, a proxy that rewrote content, or a republished file that did not bump its version. The format lists the field as optional, so a SKIP here is legitimate and not a failure.</li>
<li><strong>Runtime.</strong> If the entry resolves to <code>npx</code>, you need Node on PATH — the shipped package declares <code>node &gt;= 22</code>. If a binary distribution exists and Node does not, the runtime check is irrelevant and the script says SKIP rather than inventing a verdict.</li>
</ol>
<p>Two conditions the checker cannot see and you must check yourself: WSL is documented as unsupported for ACP agents in JetBrains IDEs, so an install attempted from a WSL-hosted project is not a supported configuration; and an offline or air-gapped machine needs a mirror for both the registry host and the artifact host, not just npm.</p>
<h2 id="reading-the-log-without-leaking-your-session">Reading the log without leaking your session</h2>
<p>You can raise log detail. The AI Assistant help page documents enabling the <code>llm.agent.extended.logging</code> registry key, which captures &ldquo;all requests sent to agents and their responses&rdquo; (<a href="https://www.jetbrains.com/help/ai-assistant/acp.html">AI Assistant ACP documentation</a>). That is the right switch for a transport-level failure and the wrong thing to paste into a public issue: agent requests contain your prompts, file paths and repository names. Before sharing, redact to the lines around the failure and strip request bodies.</p>
<p>Note what extended logging will and will not give you. The agent handshake is JSON-RPC over stdio, so once an agent launches you get request and response frames (<a href="https://agentclientprotocol.com/protocol/overview.md">ACP protocol overview</a>). An install failure happens <em>before</em> that handshake exists, which is why raising agent log verbosity often produces nothing at all — there is no session to log. Absence of ACP frames is consistent with every one of the five defects above.</p>
<h2 id="if-every-check-passes">If every check passes</h2>
<p>Then the failure is in the client&rsquo;s own install path, not in the contract, and the useful report is a set of facts rather than a stack of retries. Include: IDE product and build, AI plugin version, OS and architecture, the exact index URL, the entry&rsquo;s <code>version</code> and <code>sha256</code> from the index, the HTTP status you observed for the archive, and the SHA-256 of the bytes you actually received. That last pair is the discriminator a maintainer needs, because it separates &ldquo;we published it and you cannot reach it&rdquo; from &ldquo;you received something else&rdquo;.</p>
<p>Two honest limits on that report. The registry index is regenerated hourly, so capture the entry you saw rather than describing it from memory. And the preview channel is documented as never launched, never auth-checked and never probed for reachability — if you opted into preview, a broken artifact is expected behaviour, not a bug report.</p>
<h2 id="reproduce-it">Reproduce it</h2>
<p>Everything is first-party and offline. The scripts, the six fixtures and every transcript are in the article&rsquo;s evidence directory; no vendor code, credentials or downloads are included:</p>
<ul>
<li>checker: <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/acp_install_check.py">acp_install_check.py</a></li>
<li>stub registry: <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/acp_stub_registry.py">acp_stub_registry.py</a></li>
<li>runner: <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/run_defects.py">run_defects.py</a></li>
<li>aggregate record and environment: <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/results.json">results.json</a></li>
<li>method, including the two recorded deviations from the research plan: <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/method.md">method.md</a></li>
<li>server-side transcripts, one per case: <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/transcripts/D0_clean.jsonl">D0_clean</a>, <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/transcripts/D1_index_404.jsonl">D1_index_404</a>, <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/transcripts/D2_missing_license_url.jsonl">D2_missing_license_url</a>, <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/transcripts/D3_checksum_mismatch.jsonl">D3_checksum_mismatch</a>, <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/transcripts/D4_artifact_unreachable.jsonl">D4_artifact_unreachable</a>, <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/transcripts/D5_platform_gap.jsonl">D5_platform_gap</a></li>
<li>checker output and exit code, one per case: <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/checker/D0_clean.txt">D0_clean</a>, <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/checker/D1_index_404.txt">D1_index_404</a>, <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/checker/D2_missing_license_url.txt">D2_missing_license_url</a>, <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/checker/D3_checksum_mismatch.txt">D3_checksum_mismatch</a>, <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/checker/D4_artifact_unreachable.txt">D4_artifact_unreachable</a>, <a href="https://raw.githubusercontent.com/baeseokjae/baeseokjae.github.io/main/research/evidence/jetbrains-acp-package-install-failed-diagnosis-2026/run/checker/D5_platform_gap.txt">D5_platform_gap</a></li>
</ul>
<pre tabindex="0"><code>python3 run_defects.py --out .
python3 acp_install_check.py --registry http://127.0.0.1:8000/registry-for-jetbrains.json \
  --agent claude-acp --platform linux-x86_64
</code></pre><p>Point the second command at the real index instead of a loopback port and it becomes the pre-flight described above; the fixture is only there so the checker&rsquo;s verdicts can be audited against known-bad inputs.</p>
<p>If you are still deciding which agent to install rather than why one failed, the protocol layer is covered in <a href="/posts/ai-agent-protocols-mcp-a2a-acp-2026/">MCP, A2A and ACP compared</a>; if your failure is after launch rather than during install, process spawn and lifecycle failures are the closer analogue in <a href="/posts/mcp-stdio-transport-lifecycle-2026/">MCP stdio transport lifecycle</a>; and the agent in the measured log line is Anthropic&rsquo;s, covered in <a href="/posts/claude-code-tutorial-2026/">the Claude Code tutorial</a>.</p>
<p>The one-sentence version: the log line tells you the install did not complete, and nothing else. The check order above tells you where — and if all seven pass, you now have the evidence to say the problem is not on your machine.</p>
]]></content:encoded></item></channel></rss>