Troubleshooting

Stub

Final content will be in symptom → cause → fix format, covering the most common things that go wrong.

Topics planned:

  • "My query is slow." Check workers=, push filters into WHERE, restrict columns, and consider materialize for intermediates you'll reuse.
  • "No results from a LEFT JOIN with XMATCH." Margin cache missing on the right side, or radius too large for the cache.
  • "ValidationError: radius exceeds neighbor_margin_arcsec." Build a bigger margin cache with acid hats build-margin --margin-arcsec.
  • "ValidationError: MEDIAN not supported." Compute it yourself in Polars or pandas after r.to_polars() / r.df().
  • "ImportError on polars / pandas." Install the optional dep; pandas and polars are runtime deps of pyacid, so this shouldn't happen with a clean install — re-run pip install pyacid.
  • "Output catalog isn't recognized by LSDB." Open an issue with the directory listing; HATS spec compliance is tested but bugs happen.
  • "Windows." acid doesn't run on Windows. Use WSL2.