{"record":{"id":"87f91a7102e42e29","repo":"Crosstalk-Solutions/project-nomad","slug":"an-unknown-error-occurred-during-the-preflight-che","errorCode":null,"errorMessage":"An unknown error occurred during the preflight check.","messagePattern":"An unknown error occurred during the preflight check\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"admin/inertia/components/DownloadURLModal.tsx","lineNumber":29,"sourceCode":"  onPreflightSuccess?: (url: string) => void\n}\n\nconst DownloadURLModal: React.FC<DownloadURLModalProps> = ({\n  suggestedURL,\n  onPreflightSuccess,\n  ...modalProps\n}) => {\n  const [url, setUrl] = useState<string>('')\n  const [messages, setMessages] = useState<string[]>([])\n  const [loading, setLoading] = useState<boolean>(false)\n\n  async function runPreflightCheck(downloadUrl: string) {\n    try {\n      setLoading(true)\n      setMessages([`Running preflight check for URL: ${downloadUrl}`])\n      const res = await api.downloadRemoteMapRegionPreflight(downloadUrl)\n      if (!res) {\n        throw new Error('An unknown error occurred during the preflight check.')\n      }\n\n      if ('message' in res) {\n        throw new Error(res.message)\n      }\n\n      setMessages((prev) => [\n        ...prev,\n        `Preflight check passed. Filename: ${res.filename}, Size: ${(res.size / (1024 * 1024)).toFixed(2)} MB`,\n      ])\n\n      if (onPreflightSuccess) {\n        onPreflightSuccess(downloadUrl)\n      }\n    } catch (error) {\n      console.error('Preflight check failed:', error)\n      setMessages((prev) => [...prev, `Preflight check failed: ${error.message}`])\n    } finally {","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/Crosstalk-Solutions/project-nomad/blob/0bd1c6f4f9888d577fe232de06ac144bb8337131/admin/inertia/components/DownloadURLModal.tsx#L11-L47","documentation":"runPreflightCheck in DownloadURLModal throws this when api.downloadRemoteMapRegionPreflight(downloadUrl) resolves to a falsy value. It is the catch-all for 'the call completed but produced nothing', distinct from the next branch which surfaces a backend-provided message. The caught error's message is shown in the modal's messages list.","triggerScenarios":"The API client returns undefined/null — typical when the underlying fetch wrapper encounters a non-JSON or empty body, a cancelled request, or an unhandled backend 204; also when the endpoint was removed/renamed and the wrapper silently returns undefined.","commonSituations":"Deploying a frontend built against a newer/older backend than the API routes available; reverse proxy returning an empty body on auth redirect; CSRF/auth middleware intercepting the request and returning something the client parses to undefined.","solutions":["Check the network tab for the preflight request's actual status and body — this throw almost always hides a 4xx/5xx or empty body.","Verify the API route name/path expected by api.downloadRemoteMapRegionPreflight exists on the currently deployed backend.","Make the API wrapper throw on non-OK statuses instead of returning undefined, so real errors propagate with their status.","Validate downloadUrl is a well-formed URL before invoking the preflight."],"exampleFix":"// before\nconst res = await api.downloadRemoteMapRegionPreflight(downloadUrl)\nif (!res) {\n  throw new Error('An unknown error occurred during the preflight check.')\n}\n// after (surface whatever the wrapper swallowed)\nconst res = await api.downloadRemoteMapRegionPreflight(downloadUrl)\nif (!res) {\n  throw new Error('An unknown error occurred during the preflight check. Empty response — check auth/network and that the backend route exists.')\n}","handlingStrategy":"try-catch","validationCode":"try { new URL(downloadUrl) } catch { setMessages(['Please provide a valid URL']); return }","typeGuard":"function isPreflightSuccess(v: unknown): v is { filename: string; size: number } {\n  return typeof v === 'object' && v !== null && 'filename' in v && 'size' in v && !('message' in v)\n}","tryCatchPattern":"catch (err) { setMessages((prev) => [...prev, `Preflight failed: ${err instanceof Error ? err.message : 'unknown'}`]) }","preventionTips":["Validate the URL client-side before sending","Make the api wrapper throw on non-OK/empty bodies","Distinguish refusal (message field) from empty response in the UI copy"],"tags":["react","inertia","preflight","api-client","maps"],"backgroundTag":"empty-api-response","analyzedSha":"0bd1c6f4f9888d577fe232de06ac144bb8337131","analyzedAt":"2026-08-27T05:34:15.424Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}