Crosstalk-Solutions/project-nomad · error · Error

An unknown error occurred during the preflight check.

Error message

An unknown error occurred during the preflight check.

What it means

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.

Source

Thrown at admin/inertia/components/DownloadURLModal.tsx:29

  onPreflightSuccess?: (url: string) => void
}

const DownloadURLModal: React.FC<DownloadURLModalProps> = ({
  suggestedURL,
  onPreflightSuccess,
  ...modalProps
}) => {
  const [url, setUrl] = useState<string>('')
  const [messages, setMessages] = useState<string[]>([])
  const [loading, setLoading] = useState<boolean>(false)

  async function runPreflightCheck(downloadUrl: string) {
    try {
      setLoading(true)
      setMessages([`Running preflight check for URL: ${downloadUrl}`])
      const res = await api.downloadRemoteMapRegionPreflight(downloadUrl)
      if (!res) {
        throw new Error('An unknown error occurred during the preflight check.')
      }

      if ('message' in res) {
        throw new Error(res.message)
      }

      setMessages((prev) => [
        ...prev,
        `Preflight check passed. Filename: ${res.filename}, Size: ${(res.size / (1024 * 1024)).toFixed(2)} MB`,
      ])

      if (onPreflightSuccess) {
        onPreflightSuccess(downloadUrl)
      }
    } catch (error) {
      console.error('Preflight check failed:', error)
      setMessages((prev) => [...prev, `Preflight check failed: ${error.message}`])
    } finally {

View on GitHub (pinned to 0bd1c6f4f9)

Solutions

1. Check the network tab for the preflight request's actual status and body — this throw almost always hides a 4xx/5xx or empty body.
2. Verify the API route name/path expected by api.downloadRemoteMapRegionPreflight exists on the currently deployed backend.
3. Make the API wrapper throw on non-OK statuses instead of returning undefined, so real errors propagate with their status.
4. Validate downloadUrl is a well-formed URL before invoking the preflight.

Example fix

// before
const res = await api.downloadRemoteMapRegionPreflight(downloadUrl)
if (!res) {
  throw new Error('An unknown error occurred during the preflight check.')
}
// after (surface whatever the wrapper swallowed)
const res = await api.downloadRemoteMapRegionPreflight(downloadUrl)
if (!res) {
  throw new Error('An unknown error occurred during the preflight check. Empty response — check auth/network and that the backend route exists.')
}

try { new URL(downloadUrl) } catch { setMessages(['Please provide a valid URL']); return }

function isPreflightSuccess(v: unknown): v is { filename: string; size: number } {
  return typeof v === 'object' && v !== null && 'filename' in v && 'size' in v && !('message' in v)
}

catch (err) { setMessages((prev) => [...prev, `Preflight failed: ${err instanceof Error ? err.message : 'unknown'}`]) }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Preflight returned no data
• res.message
• No response from Ollama
• Invalid PMTiles file URL: ${url}. URL must end with .pmtiles
• Download already in progress for URL ${url}

AI-assisted analysis of Crosstalk-Solutions/project-nomad@0bd1c6f4f9 (2026-08-27). Data as JSON: /api/errors/87f91a7102e42e29. Report an issue: GitHub.