Troubleshooting Tips

This guide addresses the top 5 most frequently reported issues from Dewey's users. For each hangup, we explain what is likely happening and what steps you can take to solve it. If you'd like additional help or still have questions, check out our Discussion forum.

🏷️

= datasets commonly reported with this issue

Table of Contents

1. API and download errors
2. Jobs stuck in "Processing"
3. Customization and download threshold issues
4. Access and subscription issues
5. Tooling quick reference

1. API and download errors

403 Forbidden

A 403 error means the request was rejected before any data was transferred. This is most likely due to a missing or expired API key. To fix:

• Go to Account → API Key and generate a new key.
• Re-paste the key exactly — no extra spaces or line breaks.
• In deweypy, use ddp.set_api_key("your_key") or set the DEWEY_API_KEY environment variable.

400 Bad Request

A 400 typically means a malformed request — usually a parameter issue.

• Confirm your folder ID and API key are copied directly from your Dewey project page.
• Verify date range parameters are formatted as YYYY-MM-DD.
• If using the DuckDB tutorial, ensure get_dataset_files() URLs include the full https:// prefix. A common error: httpx.UnsupportedProtocol: Request URL is missing an 'http://' or 'https://' protocol.

🏷️

Veraset Home Visit data.

RuntimeError / CLI errors

The recommended download method is the Dewey Client. The one-liner requires no Python installation:

uvx --python 3.13 --from deweypy dewey --api-key YOUR_API_KEY speedy-download PROJECT_ID

Or install and run directly:

pip install deweypy
python -m deweypy --api-key YOUR_API_KEY speedy-download PROJECT_ID

If you are using the programmatic API and hitting errors:

• Upgrade deweypy: pip install --upgrade deweypy
• Older tutorials reference deweypy.auth and deweypy.downloads — these modules no longer exist. Use the current pattern:

import deweypy as ddp
ddp.set_api_key("your_key")
files = ddp.get_dataset_files(folder_id="your_folder_id")
ddp.download_files(files, output_dir="./data")

• For interrupted large downloads, resume with skip_exists=True to avoid re-downloading completed files:

ddp.download_files(files_df, "output_dir", skip_exists=True)

🏷️

ATTOM (assessor history via bulk API), Veraset.

500 Internal Server Error

500 errors originate server-side. Wait a few minutes and retry. If the error persists across multiple attempts over an hour or more, post in Discussions with your folder ID and the exact request URL.

💡

Bonus Tip: Start with a sample! You can download a small sample (100 rows) of any dataset by clicking Get Sample instead of Get Data on the dataset landing page. That way you can familiarize yourself with the data structure and variables, and even test your API calls on specific variables.

2. Jobs stuck in "Processing"

Expected processing times:
Most data requests complete within a few minutes. Processing time varies based on dataset size, filters applied, and current server load. If a job is still showing "Processing" after several hours with no update, it has likely stalled.

Steps to resolve:

1. Refresh the page — the status indicator sometimes doesn't update automatically.
2. Check whether the dataset recently had a refresh (see the dataset page). Refreshes can temporarily pause job queues.
3. If still stuck after several hours: remove the dataset from your project, re-add it, and submit a new request. You can also reach out to the Dewey team via the Discussion forum.

🏷️

Pass_by (Store Visitors), Advan Neighborhood Patterns Plus, filtered data requests generally.

3. Customization and download threshold issues

Customization limit reached

There are two distinct causes for customization limit messages:

Cause A — Daily customization limit (2/day)

Dewey enforces a limit of 2 dataset customizations per day per user. The platform will show:

"You've hit the daily limit of 2/day for dataset customizations. Since this dataset requires customization, please wait until your limit resets and try again."

• The limit resets the next calendar day.
• If you need to access data that requires customization more frequently, contact the Dewey team.

🏷️

ATTOM (datasets that require customization to meet the row threshold).

Cause B — "Free customization preview limit reached" (10 previews)

Users are allotted 10 free customization previews per day. Once exhausted, the platform will show "Free customization preview limit reached."

• This can happen regardless of subscription status — it is not always a subscription recognition issue.
• The limit resets after a 24-hour period.

Cause C — "Free customization preview limit reached" (subscription not recognized)

This message appears when the platform does not recognize an active subscription during the customization flow.

• Log out and log back in using your institutional email.
• If your university uses SSO, use your institution's SSO link — logging in directly at deweydata.io may not pick up institutional access.

No way to filter below the download threshold

For most datasets, you can download without filtering by pressing Skip. But some datasets require the progress bar in the Customize modal to turn green before downloading proceeds.

• Stack multiple filters (date range, geography, attribute filters) to reduce row count.
• Use Select Columns to drop unneeded columns. This reduces file size but does not count toward the row threshold.
• Use the Dewey Client with date partitioning (for date-partitioned datasets) to download in segments, bypassing the UI threshold entirely:

python -m deweypy --api-key YOUR_KEY speedy-download PROJECT_ID \
  --partition-key-after 2023-01-01 --partition-key-before 2023-12-31

• If none of the above work, contact the Dewey team — filter options can sometimes be expanded.

⚠️

Note: each UI customization attempt counts toward your 2/day limit (see above), so plan your filter combinations before submitting.

🏷️

ATTOM (Recorder, Tax Assessor History, School Attendance Boundaries), LinkUp Job Records.

4. Access and subscription issues

"Get Data" button is grayed out

• Datasets must be added to a Projects folder. Create a project and click Add Datasets from your project page, or choose an existing project when adding data from the catalog page.
• If you believe a dataset should be included in your institutional subscription, check Subscriptions Explained for the full list — some datasets (all ATTOM, all Veraset, PDL People and Resume) require an institutional license and are not available on individual Researcher subscriptions.

🏷️

ATTOM, Veraset, PDL People and Resume.

Downloader role set but API returns a permissions error

If you see: "You do not have permission to download this dataset through this Project" —

• This means you may have access through a different project, but not the one you're currently attempting to download from. Confirm which project the dataset lives in and copy the Folder ID from that specific project's API tab — folder IDs are not interchangeable across projects.
• If your Downloader role was recently assigned, note that role approval takes up to two business days. Your access may simply not be active yet.

Project shows "no datasets found" or folders disappeared

• Try removing the dataset and re-adding it via Get Data.
• Check whether your subscription has lapsed, or whether you've hit your plan's active project limit — paid subscribers can only have a set number of projects in "Working" or "Exploring" status simultaneously. Archiving an unused project may restore access.

5. Tooling quick reference

For full setup guides, see Quickstart: Dewey Client, Using DuckDB with Dewey, and Working with R. This section covers issues not addressed in those docs.

Outdated tutorial references

Some older documentation still references a deprecated deweypy module structure:

DuckDB: missing https:// prefix

A common error when following the DuckDB tutorial is passing a URL without the https:// prefix to get_dataset_files(), which produces httpx.UnsupportedProtocol. Ensure the full URL is passed as returned by the API.

Veraset: placekey not visible in preview

preview_dewey_duck() doesn't surface the placekey column, but it exists in the data. Call the API without a SELECT clause, or explicitly include placekey in your column list.

Still need help?

Search or post in Dewey Discussions with the details.