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:
'schemas/person.json' doesn't existError 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:
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.
Other errors
Section titled “Other errors”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. |