Skip to content

Errors

When a request fails, session.fetch rejects with a TypeError the way fetch does for a network error. A browser gives a network error for a file that doesn’t exist, a scheme it doesn’t support, and a redirect it won’t follow, so a Hyperjump session does too. A failure is never an error response like a 404, because no server answered.

The error’s message says what went wrong and names the URL, so you can show it to a person:

Output
'schemas/person.json' doesn't exist

Error messages often end up in logs and bug reports. To keep them from revealing where your files are, a message shows a file: URL relative to the working directory. The error’s url has the whole URL. If you want your own messages to show URLs the same way, use relativeFileUrl(url).

To tell failures apart in code, use the error’s cause.code:

TypeScript
const load = async (url: string) => {
try {
return await session.fetch(url);
} catch (error) {
const code = (error as { cause?: { code?: string } }).cause?.code;
if (code === "ENOENT") {
// The file doesn't exist
} else if (code === "ERR_RETRIEVAL_NOT_ALLOWED") {
// The session's allowRetrieval doesn't allow the URL
}
throw error;
}
};

When the filesystem or the network fails, cause is the error it gave, with its code. Node.js’s own fetch gives the reason the same way. An aborted request rejects with the signal’s reason, as it does with fetch, so it isn’t a network error.

Code What failed
ERR_RETRIEVAL_NOT_ALLOWED The URL, where a redirect leads, or the response’s URL isn’t in the session’s allowRetrieval. For more information, see What a session can fetch.
ERR_FILE_REFERENCE_NOT_ALLOWED A document that isn’t a file referred to a file: URL. For more information, see File URLs.
ERR_UNEXPECTED_REDIRECT The response redirected, and the request’s redirect is "error".
ERR_REDIRECT_NOT_FOLLOWED In a browser, a request whose method isn’t idempotent, such as POST, redirected. The server got the request, and following the redirect would send it again. For more information, see Redirects.
ERR_TOO_MANY_REDIRECTS The request redirected more times than the session’s maxRedirects.
ERR_INVALID_REDIRECT A redirect’s Location isn’t a URL, or has a username or password in it.
ERR_UNSAFE_REDIRECT A redirect led to a file: URL, or to a scheme that isn’t in the session’s redirectSchemes. For more information, see Redirects.
ERR_CACHE_MISS The request’s cache is "only-if-cached", and no cache has the response.
ERR_UNKNOWN_URL_SCHEME The transport doesn’t have a fetcher for the URL’s scheme. For more information, see Transports.
ERR_METHOD_NOT_SUPPORTED A request for a file: URL used a method other than GET or HEAD.
ERR_OUTSIDE_ROOT A file: URL is outside the file: scheme’s root.
ERR_NOT_A_FILE A file: URL is a directory, or something else that isn’t a file.
ENOENT, EACCES, and other codes from the filesystem A file doesn’t exist, or the session can’t read it.
ENOTFOUND, ECONNREFUSED, and other codes from the runtime The runtime’s fetch failed, such as for a host that isn’t found or a server that refused the connection.

A failed request shows in a trace with its message. For more information, see Tracing.

A failure that isn’t a network error works the same way: it’s an error whose cause.code says why, with the URL it’s about as its url.

Codes From
ERR_HTTP_STATUS, ERR_UNSUPPORTED_MEDIA_TYPE, ERR_ABSOLUTE_FILE_URL, ERR_ANCHOR_NOT_FOUND, ERR_REFERENCE_CYCLE, ERR_TOO_MANY_REFERENCES, ERR_SYNTAX browse. For more information, see Browse to a URL.
ERR_POINTER_NOT_FOUND, ERR_POINTER_INVALID_INDEX, ERR_POINTER_DUPLICATE_PROPERTY, ERR_POINTER_NOT_INDEXABLE, ERR_INVALID_VALUE The functions that read an AST. For more information, see Parse JSON and JRef.
ERR_STRUCTURED_VALUE jrefValue. For more information, see Read values.
ERR_MAX_DEPTH jrefVisit, jrefFind, jrefFindAll, jrefSelect, and jrefSelectAll. For more information, see Read values.
ERR_MAX_REVISITS jrefVisit. For more information, see Read values.