My import failed
Import blocked or errored? Check the file limits, map every required field, and for Paymo supply a valid API key with all users mapped.
Most failed imports come down to a file that's outside the limits, a required field left unmapped, or a Paymo connection that's missing a key or a user mapping. Here's how to clear each.
Most likely cause
- File limits. CSV imports allow up to 5 MB, 10,000 rows, and 200 columns, and must
be a single sheet — a multi-sheet
.xlsxis rejected. - Unmapped required fields. If required fields aren't mapped, Preview is blocked. Required fields are: Client → name; Project → name + client; Time entry → date + project + user + hours.
- Paymo specifics. A Paymo import needs a valid API key (re-paste it when you resume) and every Paymo user mapped to a member.
How to check
- File size and shape. Confirm the file is under the size/row/column limits and is a single sheet.
- Mapping screen. If you can't reach Preview, a required field is still unmapped — the mapper will flag which.
- Paymo key and users. For Paymo, verify the API key is valid and that no user is left unmapped.
- Another import running? Only one import runs at a time per workspace — a second won't start until the first finishes.
How to fix
Bring the file within limits
Split or trim the file to stay under 5 MB / 10,000 rows / 200 columns, and export a single
sheet — convert a multi-sheet .xlsx to one sheet (or CSV) first.
Map every required field
On the mapping step, map all required columns: Client (name), Project (name + client), or Time entry (date + project + user + hours). Preview unlocks once they're set.
Fix the Paymo connection
For Paymo, re-paste a valid API key (especially when resuming a job) and map every Paymo user to a Hoursmith member.
Resume or undo
You can Resume a stalled job rather than starting over. Re-uploading the same file is a safe no-op, so don't worry about duplicates. If an import went in wrong, you can Undo it within 24 hours.
Re-uploading an identical file is a safe no-op — it won't create duplicate records — so it's fine to retry after fixing a mapping.
Still stuck?
If the file is within limits, every required field and Paymo user is mapped, and the import still fails, email hi@hoursmith.app. Detailed guides: Import CSV and Import from Paymo.
A member can't see invoices
This is by design — Members are money-blind and have no access to invoices, amounts, rates, expenses, or clients. Give them Manager+ if they need it.
API token issues
Getting 401, 402, 403, or 429 from the Hoursmith API? Each maps to a specific cause — bad token, plan, role, or rate limit. Here's how to fix each.