Page
https://www.elastic.co/docs/explore-analyze/ai-features/ai-chat-experiences/ai-assistant-host-doc-artifacts
Problem
The Local files on the Kibana host section instructs users to place the ZIP files in a directory and set xpack.productDocBase.artifactRepositoryUrl to a file:// URL pointing at that directory. It does not mention any additional files being required.
However, the Kibana source code shows that when a file:// URL is used, Kibana does not scan the directory for ZIPs. Instead, it unconditionally looks for an index.xml file in that directory and parses it as an S3-style ListBucketResult XML listing. If index.xml is absent, artifact discovery fails with no useful error surfaced to the user.
Relevant code in fetch_artifact_versions.ts (identical in 8.19.15 and 9.1.x):
function fetchLocalFile(parsedUrl: URL): Promise<Buffer> {
return new Promise((resolve, reject) => {
const normalizedPath = resolveLocalArtifactsPath(parsedUrl);
const xmlFilePath = Path.join(normalizedPath, 'index.xml'); // hardcoded
fs.readFile(xmlFilePath, (err, data) => {
if (err) {
reject(err); // no index.xml = immediate rejection, no fallback
} else {
resolve(data);
}
});
});
}And the caller:
if (parsedUrl.protocol === 'file:') {
const file = await fetchLocalFile(parsedUrl); // always requires index.xml
xml = file.toString();
} else {
const res = await fetch(`${artifactRepositoryUrl}?max-keys=1000`);
xml = await res.text();
}What the docs should add
The local files section should state that index.xml must be present in the same directory as the ZIPs, using the same ListBucketResult XML format described in the CDN section. For example, for Kibana 8.19:
<ListBucketResult>
<Name>kibana-ai-assistant-kb-artifacts</Name>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>kb-product-doc-elasticsearch-8.19.zip</Key>
</Contents>
<Contents>
<Key>kb-product-doc-kibana-8.19.zip</Key>
</Contents>
<Contents>
<Key>kb-product-doc-observability-8.19.zip</Key>
</Contents>
<Contents>
<Key>kb-product-doc-security-8.19.zip</Key>
</Contents>
</ListBucketResult>The expected directory layout should also be shown:
/path/to/artifacts/
├── index.xml
├── kb-product-doc-elasticsearch-<major>.<minor>.zip
├── kb-product-doc-kibana-<major>.<minor>.zip
├── kb-product-doc-observability-<major>.<minor>.zip
└── kb-product-doc-security-<major>.<minor>.zip
Impact
Users following the current docs will silently fail to load KB artifacts with no clear error. This was encountered in a customer support case involving an air-gapped ECK/OpenShift deployment.
Page
https://www.elastic.co/docs/explore-analyze/ai-features/ai-chat-experiences/ai-assistant-host-doc-artifacts
Problem
The Local files on the Kibana host section instructs users to place the ZIP files in a directory and set
xpack.productDocBase.artifactRepositoryUrlto afile://URL pointing at that directory. It does not mention any additional files being required.However, the Kibana source code shows that when a
file://URL is used, Kibana does not scan the directory for ZIPs. Instead, it unconditionally looks for anindex.xmlfile in that directory and parses it as an S3-styleListBucketResultXML listing. Ifindex.xmlis absent, artifact discovery fails with no useful error surfaced to the user.Relevant code in
fetch_artifact_versions.ts(identical in 8.19.15 and 9.1.x):And the caller:
What the docs should add
The local files section should state that
index.xmlmust be present in the same directory as the ZIPs, using the sameListBucketResultXML format described in the CDN section. For example, for Kibana 8.19:The expected directory layout should also be shown:
Impact
Users following the current docs will silently fail to load KB artifacts with no clear error. This was encountered in a customer support case involving an air-gapped ECK/OpenShift deployment.