Refactor lib for better readability

**Problem**
When working with lib, the error messages could be more descriptive.

**Suggestion**
Improve error handling and add detailed error messages.

**Context**
This would help with debugging and maintenance.

The issue only points to lib and does not name files, entry points, or tests. Start by reviewing lib’s current error-handling paths and clarify which messages need changing; done means the agreed error cases have more descriptive messages and the relevant behavior is verified.

Written by the indexing model from the issue text.