fix: verbose error messages in all release providers

Every error now includes a diagnostic message:
- noMatchingVersion: shows the regex used, how many tags were
  checked, and sample tag names so users can see why matching failed
- noReleasesFound: distinguishes "no releases at all" from "no match"
- invalidIdentifier: shows the problematic identifier string
- unexpected: includes HTTP status codes from provider APIs

getLatestRelease returns { release } | { noMatch: reason } instead
of Release | null, carrying the diagnostic through.
This commit is contained in:
Thomas Camlong committed 2026-06-27 10:57:14 +02:00
1 parent d893515b93
commit 2155f13f24
1 file changed
+76 -46
@@ -37,23 +37,34 @@ export interface ReleaseProviderResponse {
} }
export type ReleaseData = DetailsProviderResponse & ReleaseProviderResponse; export type ReleaseData = DetailsProviderResponse & ReleaseProviderResponse;
export type ReleaseError = export type ReleaseError = { code: "invalidIdentifier" | "noMatchingVersion" | "noReleasesFound" | "unexpected"; message: string };
| { code: "invalidIdentifier" | "noMatchingVersion" | "noReleasesFound" }
| { code: "unexpected"; message: string };
export type ReleaseResponse = { success: true; data: ReleaseData } | { success: false; error: ReleaseError }; export type ReleaseResponse = { success: true; data: ReleaseData } | { success: false; error: ReleaseError };
export const getLatestRelease = ( export const getLatestRelease = (
releases: ReleaseProviderResponse[], releases: ReleaseProviderResponse[],
versionRegex?: string, versionRegex?: string,
): ReleaseProviderResponse | null => { ): { release: ReleaseProviderResponse } | { noMatch: string } => {
const validReleases = releases.filter((result) => { const validReleases = releases.filter((result) => {
if (!result.latestRelease) return false; if (!result.latestRelease) return false;
return versionRegex ? new RegExp(versionRegex).test(result.latestRelease) : true; return versionRegex ? new RegExp(versionRegex).test(result.latestRelease) : true;
}); });
return validReleases.length === 0 if (validReleases.length > 0) {
? null return {
: validReleases.reduce((latest, current) => (current.latestReleaseAt > latest.latestReleaseAt ? current : latest)); release: validReleases.reduce((latest, current) =>
current.latestReleaseAt > latest.latestReleaseAt ? current : latest,
),
};
}
const sampleTags = releases
.slice(0, 5)
.map((r) => r.latestRelease)
.join(", ");
const reason = versionRegex
? `Regex /${versionRegex}/ matched 0/${releases.length} tags. Sample tags: [${sampleTags}]`
: `Found ${releases.length} releases but none had a valid tag`;
return { noMatch: reason };
}; };
export const getLatestMatchingReleaseAsync = async (input: ReleasesRepositoryRequest): Promise<ReleaseResponse> => { export const getLatestMatchingReleaseAsync = async (input: ReleasesRepositoryRequest): Promise<ReleaseResponse> => {
@@ -113,12 +124,14 @@ const getGithubReleaseAsync = async (
token?: string, token?: string,
): Promise<ReleaseResponse> => { ): Promise<ReleaseResponse> => {
const parsed = parseOwnerName(identifier); const parsed = parseOwnerName(identifier);
if (!parsed) return { success: false, error: { code: "invalidIdentifier" } }; if (!parsed) return { success: false, error: { code: "invalidIdentifier", message: `Cannot parse "${identifier}" as owner/repo` } };
const api = getGithubApi(baseUrl, "Homarr-Lab/Homarr:GithubReleaseProvider", token); const api = getGithubApi(baseUrl, "Homarr-Lab/Homarr:GithubReleaseProvider", token);
try { try {
const releasesResponse = await api.rest.repos.listReleases({ owner: parsed.owner, repo: parsed.name }); const releasesResponse = await api.rest.repos.listReleases({ owner: parsed.owner, repo: parsed.name });
if (releasesResponse.data.length === 0) return { success: false, error: { code: "noMatchingVersion" } }; if (releasesResponse.data.length === 0) {
return { success: false, error: { code: "noReleasesFound", message: `${identifier} has no GitHub releases` } };
}
const releases = releasesResponse.data.reduce<ReleaseProviderResponse[]>((acc, release) => { const releases = releasesResponse.data.reduce<ReleaseProviderResponse[]>((acc, release) => {
if (!release.published_at) return acc; if (!release.published_at) return acc;
@@ -131,11 +144,13 @@ const getGithubReleaseAsync = async (
}); });
return acc; return acc;
}, []); }, []);
const latestRelease = getLatestRelease(releases, versionRegex); const result = getLatestRelease(releases, versionRegex);
if (!latestRelease) return { success: false, error: { code: "noMatchingVersion" } }; if ("noMatch" in result) {
return { success: false, error: { code: "noMatchingVersion", message: result.noMatch } };
}
const details = await getGithubDetailsAsync(api, parsed.owner, parsed.name); const details = await getGithubDetailsAsync(api, parsed.owner, parsed.name);
return { success: true, data: { ...details, ...latestRelease } }; return { success: true, data: { ...details, ...result.release } };
} catch (error) { } catch (error) {
const message = error instanceof OctokitRequestError ? error.message : String(error); const message = error instanceof OctokitRequestError ? error.message : String(error);
logger.warn("Failed to get GitHub releases", { identifier, error: message }); logger.warn("Failed to get GitHub releases", { identifier, error: message });
@@ -169,20 +184,29 @@ const getGitHubContainerRegistryReleaseAsync = async (
token?: string, token?: string,
): Promise<ReleaseResponse> => { ): Promise<ReleaseResponse> => {
const parsed = parseOwnerPackageName(identifier); const parsed = parseOwnerPackageName(identifier);
if (!parsed) return { success: false, error: { code: "invalidIdentifier" } }; if (!parsed) return { success: false, error: { code: "invalidIdentifier", message: `Cannot parse "${identifier}" as owner/package` } };
try { try {
const repositoryName = `${parsed.owner}/${parsed.name}`; const repositoryName = `${parsed.owner}/${parsed.name}`;
const registryUrl = new URL(baseUrl); const registryUrl = new URL(baseUrl);
const registryToken = token ?? (await getGitHubContainerRegistryTokenAsync(registryUrl, repositoryName)); const registryToken = token ?? (await getGitHubContainerRegistryTokenAsync(registryUrl, repositoryName));
const tags = await getGitHubContainerRegistryTagsAsync(registryUrl, repositoryName, registryToken); const tags = await getGitHubContainerRegistryTagsAsync(registryUrl, repositoryName, registryToken);
if (tags.length === 0) {
return { success: false, error: { code: "noReleasesFound", message: `${repositoryName} has no container tags` } };
}
const matchingTags = versionRegex ? tags.filter((tag) => new RegExp(versionRegex).test(tag)) : tags; const matchingTags = versionRegex ? tags.filter((tag) => new RegExp(versionRegex).test(tag)) : tags;
const tagsToCheck = versionRegex const tagsToCheck = versionRegex
? matchingTags.slice(-100) ? matchingTags.slice(-100)
: matchingTags.includes("latest") : matchingTags.includes("latest")
? ["latest"] ? ["latest"]
: matchingTags.slice(-100); : matchingTags.slice(-100);
if (tagsToCheck.length === 0) return { success: false, error: { code: "noMatchingVersion" } }; if (tagsToCheck.length === 0) {
const sampleTags = tags.slice(0, 5).join(", ");
const msg = versionRegex
? `Regex /${versionRegex}/ matched 0/${tags.length} tags. Sample: [${sampleTags}]`
: `No "latest" tag found among ${tags.length} tags. Sample: [${sampleTags}]`;
return { success: false, error: { code: "noMatchingVersion", message: msg } };
}
const releases = await Promise.all( const releases = await Promise.all(
tagsToCheck.map(async (tag) => ({ tagsToCheck.map(async (tag) => ({
@@ -196,14 +220,16 @@ const getGitHubContainerRegistryReleaseAsync = async (
releaseUrl: `https://github.com/${repositoryName}/pkgs/container/${encodeURIComponent(parsed.name)}`, releaseUrl: `https://github.com/${repositoryName}/pkgs/container/${encodeURIComponent(parsed.name)}`,
})), })),
); );
const latestRelease = getLatestRelease(releases, versionRegex); const result = getLatestRelease(releases, versionRegex);
if (!latestRelease) return { success: false, error: { code: "noMatchingVersion" } }; if ("noMatch" in result) {
return { success: false, error: { code: "noMatchingVersion", message: result.noMatch } };
}
return { return {
success: true, success: true,
data: { data: {
projectUrl: `https://github.com/${repositoryName}`, projectUrl: `https://github.com/${repositoryName}`,
...latestRelease, ...result.release,
}, },
}; };
} catch (error) { } catch (error) {
@@ -335,7 +361,7 @@ const getDockerHubReleaseAsync = async (
token?: string, token?: string,
): Promise<ReleaseResponse> => { ): Promise<ReleaseResponse> => {
const parsed = identifier.includes("/") ? parseOwnerName(identifier) : { owner: "", name: identifier }; const parsed = identifier.includes("/") ? parseOwnerName(identifier) : { owner: "", name: identifier };
if (!parsed) return { success: false, error: { code: "invalidIdentifier" } }; if (!parsed) return { success: false, error: { code: "invalidIdentifier", message: `Cannot parse "${identifier}"` } };
const relativeUrl = parsed.owner const relativeUrl = parsed.owner
? `/v2/namespaces/${encodeURIComponent(parsed.owner)}/repositories/${encodeURIComponent(parsed.name)}` ? `/v2/namespaces/${encodeURIComponent(parsed.owner)}/repositories/${encodeURIComponent(parsed.name)}`
@@ -344,25 +370,29 @@ const getDockerHubReleaseAsync = async (
const headers: Record<string, string> = {}; const headers: Record<string, string> = {};
if (token) headers.Authorization = `Bearer ${token}`; if (token) headers.Authorization = `Bearer ${token}`;
let lastNoMatch = "";
for (let page = 0; page <= 5; page++) { for (let page = 0; page <= 5; page++) {
const response = await fetchWithTrustedCertificatesAsync( const response = await fetchWithTrustedCertificatesAsync(
buildUrl(baseUrl, `${relativeUrl}/tags?page_size=100&page=${page}` as `/${string}`), buildUrl(baseUrl, `${relativeUrl}/tags?page_size=100&page=${page}` as `/${string}`),
headers.Authorization ? { headers } : undefined, headers.Authorization ? { headers } : undefined,
); );
if (!response.ok) return { success: false, error: { code: "unexpected", message: response.statusText } }; if (!response.ok) return { success: false, error: { code: "unexpected", message: `Docker Hub ${response.status}: ${response.statusText}` } };
const json: unknown = await response.json(); const json: unknown = await response.json();
const result = dockerHubReleasesSchema.safeParse(json); const result = dockerHubReleasesSchema.safeParse(json);
if (!result.success) return { success: false, error: { code: "unexpected", message: result.error.message } }; if (!result.success) return { success: false, error: { code: "unexpected", message: result.error.message } };
const latestRelease = getLatestRelease(result.data.results, versionRegex); const matched = getLatestRelease(result.data.results, versionRegex);
if (!latestRelease) continue; if ("noMatch" in matched) {
lastNoMatch = matched.noMatch;
continue;
}
const details = await getDockerHubDetailsAsync(baseUrl, relativeUrl as `/${string}`, token); const details = await getDockerHubDetailsAsync(baseUrl, relativeUrl as `/${string}`, token);
return { success: true, data: { ...details, ...latestRelease } }; return { success: true, data: { ...details, ...matched.release } };
} }
return { success: false, error: { code: "noMatchingVersion" } }; return { success: false, error: { code: "noMatchingVersion", message: lastNoMatch || `No matching tags found for ${identifier}` } };
}; };
const getDockerHubDetailsAsync = async ( const getDockerHubDetailsAsync = async (
@@ -425,11 +455,11 @@ const getGitlabReleaseAsync = async (
buildUrl(baseUrl, `/api/v4/projects/${encodedIdentifier}/releases?per_page=100`), buildUrl(baseUrl, `/api/v4/projects/${encodedIdentifier}/releases?per_page=100`),
headers["PRIVATE-TOKEN"] ? { headers } : undefined, headers["PRIVATE-TOKEN"] ? { headers } : undefined,
); );
if (!response.ok) return { success: false, error: { code: "unexpected", message: response.statusText } }; if (!response.ok) return { success: false, error: { code: "unexpected", message: `GitLab ${response.status}: ${response.statusText}` } };
const result = gitlabReleasesSchema.safeParse(await response.json()); const result = gitlabReleasesSchema.safeParse(await response.json());
if (!result.success) return { success: false, error: { code: "unexpected", message: result.error.message } }; if (!result.success) return { success: false, error: { code: "unexpected", message: result.error.message } };
if (result.data.length === 0) return { success: false, error: { code: "noReleasesFound" } }; if (result.data.length === 0) return { success: false, error: { code: "noReleasesFound", message: `${identifier} has no GitLab releases` } };
const releases = result.data.reduce<ReleaseProviderResponse[]>((acc, release) => { const releases = result.data.reduce<ReleaseProviderResponse[]>((acc, release) => {
if (!release.released_at) return acc; if (!release.released_at) return acc;
@@ -443,11 +473,11 @@ const getGitlabReleaseAsync = async (
}); });
return acc; return acc;
}, []); }, []);
const latestRelease = getLatestRelease(releases, versionRegex); const matched = getLatestRelease(releases, versionRegex);
if (!latestRelease) return { success: false, error: { code: "noMatchingVersion" } }; if ("noMatch" in matched) return { success: false, error: { code: "noMatchingVersion", message: matched.noMatch } };
const details = await getGitlabDetailsAsync(baseUrl, encodedIdentifier, token); const details = await getGitlabDetailsAsync(baseUrl, encodedIdentifier, token);
return { success: true, data: { ...details, ...latestRelease } }; return { success: true, data: { ...details, ...matched.release } };
}; };
const getGitlabDetailsAsync = async ( const getGitlabDetailsAsync = async (
@@ -502,7 +532,7 @@ const getNpmReleaseAsync = async (
versionRegex?: string, versionRegex?: string,
token?: string, token?: string,
): Promise<ReleaseResponse> => { ): Promise<ReleaseResponse> => {
if (!identifier) return { success: false, error: { code: "invalidIdentifier" } }; if (!identifier) return { success: false, error: { code: "invalidIdentifier", message: "Empty npm package name" } };
const headers: Record<string, string> = {}; const headers: Record<string, string> = {};
if (token) headers.Authorization = `Bearer ${token}`; if (token) headers.Authorization = `Bearer ${token}`;
@@ -511,7 +541,7 @@ const getNpmReleaseAsync = async (
buildUrl(baseUrl, `/${encodeURIComponent(identifier)}`), buildUrl(baseUrl, `/${encodeURIComponent(identifier)}`),
headers.Authorization ? { headers } : undefined, headers.Authorization ? { headers } : undefined,
); );
if (!response.ok) return { success: false, error: { code: "unexpected", message: response.statusText } }; if (!response.ok) return { success: false, error: { code: "unexpected", message: `npm ${response.status}: ${response.statusText}` } };
const result = npmReleasesSchema.safeParse(await response.json()); const result = npmReleasesSchema.safeParse(await response.json());
if (!result.success) return { success: false, error: { code: "unexpected", message: result.error.message } }; if (!result.success) return { success: false, error: { code: "unexpected", message: result.error.message } };
@@ -521,10 +551,10 @@ const getNpmReleaseAsync = async (
releaseUrl: `https://www.npmjs.com/package/${encodeURIComponent(result.data.name)}/v/${encodeURIComponent(tag.latestRelease)}`, releaseUrl: `https://www.npmjs.com/package/${encodeURIComponent(result.data.name)}/v/${encodeURIComponent(tag.latestRelease)}`,
releaseDescription: result.data.versions[tag.latestRelease]?.description ?? "", releaseDescription: result.data.versions[tag.latestRelease]?.description ?? "",
})); }));
const latestRelease = getLatestRelease(releases, versionRegex); const matched = getLatestRelease(releases, versionRegex);
if (!latestRelease) return { success: false, error: { code: "noMatchingVersion" } }; if ("noMatch" in matched) return { success: false, error: { code: "noMatchingVersion", message: matched.noMatch } };
return { success: true, data: latestRelease }; return { success: true, data: matched.release };
}; };
const codebergReleasesSchema = z.array( const codebergReleasesSchema = z.array(
@@ -555,7 +585,7 @@ const getCodebergReleaseAsync = async (
token?: string, token?: string,
): Promise<ReleaseResponse> => { ): Promise<ReleaseResponse> => {
const parsed = parseOwnerName(identifier); const parsed = parseOwnerName(identifier);
if (!parsed) return { success: false, error: { code: "invalidIdentifier" } }; if (!parsed) return { success: false, error: { code: "invalidIdentifier", message: `Cannot parse "${identifier}" as owner/repo` } };
const headers: Record<string, string> = {}; const headers: Record<string, string> = {};
if (token) headers.Authorization = `token ${token}`; if (token) headers.Authorization = `token ${token}`;
@@ -564,7 +594,7 @@ const getCodebergReleaseAsync = async (
buildUrl(baseUrl, `/api/v1/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.name)}/releases`), buildUrl(baseUrl, `/api/v1/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.name)}/releases`),
headers.Authorization ? { headers } : undefined, headers.Authorization ? { headers } : undefined,
); );
if (!response.ok) return { success: false, error: { code: "unexpected", message: response.statusText } }; if (!response.ok) return { success: false, error: { code: "unexpected", message: `Codeberg ${response.status}: ${response.statusText}` } };
const result = codebergReleasesSchema.safeParse(await response.json()); const result = codebergReleasesSchema.safeParse(await response.json());
if (!result.success) return { success: false, error: { code: "unexpected", message: result.error.message } }; if (!result.success) return { success: false, error: { code: "unexpected", message: result.error.message } };
@@ -576,11 +606,11 @@ const getCodebergReleaseAsync = async (
releaseDescription: tag.body, releaseDescription: tag.body,
isPreRelease: tag.prerelease, isPreRelease: tag.prerelease,
})); }));
const latestRelease = getLatestRelease(releases, versionRegex); const matched = getLatestRelease(releases, versionRegex);
if (!latestRelease) return { success: false, error: { code: "noMatchingVersion" } }; if ("noMatch" in matched) return { success: false, error: { code: "noMatchingVersion", message: matched.noMatch } };
const details = await getCodebergDetailsAsync(baseUrl, parsed.owner, parsed.name, token); const details = await getCodebergDetailsAsync(baseUrl, parsed.owner, parsed.name, token);
return { success: true, data: { ...details, ...latestRelease } }; return { success: true, data: { ...details, ...matched.release } };
}; };
const getCodebergDetailsAsync = async ( const getCodebergDetailsAsync = async (
@@ -638,16 +668,16 @@ const linuxServerIOReleasesSchema = z.object({
const getLinuxServerIOReleaseAsync = async (baseUrl: string, identifier: string): Promise<ReleaseResponse> => { const getLinuxServerIOReleaseAsync = async (baseUrl: string, identifier: string): Promise<ReleaseResponse> => {
const parsed = parseOwnerName(identifier); const parsed = parseOwnerName(identifier);
if (!parsed) return { success: false, error: { code: "invalidIdentifier" } }; if (!parsed) return { success: false, error: { code: "invalidIdentifier", message: `Cannot parse "${identifier}" as owner/name` } };
const response = await fetchWithTrustedCertificatesAsync(buildUrl(baseUrl, "/api/v1/images")); const response = await fetchWithTrustedCertificatesAsync(buildUrl(baseUrl, "/api/v1/images"));
if (!response.ok) return { success: false, error: { code: "unexpected", message: response.statusText } }; if (!response.ok) return { success: false, error: { code: "unexpected", message: `LSIO ${response.status}: ${response.statusText}` } };
const result = linuxServerIOReleasesSchema.safeParse(await response.json()); const result = linuxServerIOReleasesSchema.safeParse(await response.json());
if (!result.success) return { success: false, error: { code: "unexpected", message: result.error.message } }; if (!result.success) return { success: false, error: { code: "unexpected", message: result.error.message } };
const release = result.data.data.repositories.linuxserver.find((repo) => repo.name === parsed.name); const release = result.data.data.repositories.linuxserver.find((repo) => repo.name === parsed.name);
if (!release) return { success: false, error: { code: "noMatchingVersion" } }; if (!release) return { success: false, error: { code: "noReleasesFound", message: `Image "${parsed.name}" not found in LinuxServer.io registry` } };
return { return {
success: true, success: true,
@@ -675,7 +705,7 @@ const getQuayReleaseAsync = async (
versionRegex?: string, versionRegex?: string,
): Promise<ReleaseResponse> => { ): Promise<ReleaseResponse> => {
const parsed = parseOwnerName(identifier); const parsed = parseOwnerName(identifier);
if (!parsed) return { success: false, error: { code: "invalidIdentifier" } }; if (!parsed) return { success: false, error: { code: "invalidIdentifier", message: `Cannot parse "${identifier}" as owner/repo` } };
const response = await fetchWithTrustedCertificatesAsync( const response = await fetchWithTrustedCertificatesAsync(
buildUrl( buildUrl(
@@ -683,7 +713,7 @@ const getQuayReleaseAsync = async (
`/api/v1/repository/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.name)}?includeTags=true&includeStats=true`, `/api/v1/repository/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.name)}?includeTags=true&includeStats=true`,
), ),
); );
if (!response.ok) return { success: false, error: { code: "unexpected", message: response.statusText } }; if (!response.ok) return { success: false, error: { code: "unexpected", message: `Quay ${response.status}: ${response.statusText}` } };
const result = quayReleasesSchema.safeParse(await response.json()); const result = quayReleasesSchema.safeParse(await response.json());
if (!result.success) return { success: false, error: { code: "unexpected", message: result.error.message } }; if (!result.success) return { success: false, error: { code: "unexpected", message: result.error.message } };
@@ -697,8 +727,8 @@ const getQuayReleaseAsync = async (
}); });
return acc; return acc;
}, []); }, []);
const latestRelease = getLatestRelease(releases, versionRegex); const matched = getLatestRelease(releases, versionRegex);
if (!latestRelease) return { success: false, error: { code: "noMatchingVersion" } }; if ("noMatch" in matched) return { success: false, error: { code: "noMatchingVersion", message: matched.noMatch } };
return { success: true, data: { projectDescription: result.data.description, ...latestRelease } }; return { success: true, data: { projectDescription: result.data.description, ...matched.release } };
}; };