Troubleshooting

This page collects common problems and fixes. If something is still unclear, ask for help on GitHub or Discord.

Python command not found

Try:

python3 --version

or:

py --version

If none of these work, Python may not be installed or may not be added to your system path.

Virtual environment will not activate

Make sure the virtual environment exists:

python -m venv .venv

On Linux or macOS:

source .venv/bin/activate

On Windows PowerShell:

.venv\Scripts\Activate.ps1

If PowerShell blocks activation, your execution policy may need to be changed. Ask for help if you are unsure.

Ruff command not found

Make sure your virtual environment is active. Then install requirements:

pip install -r requirements.txt

Try again:

ruff check .

App does not start

Check that:

• you are inside the project folder
• your virtual environment is active
• requirements are installed
• you are running python -m pynventory.main from the repository root

If the app prints an error, copy the full error message when asking for help.

data/products.db appears as modified

The app uses a local SQLite database file named data/products.db. Running the app may change this file.

The data/ folder is tracked with data/.gitkeep, but data/products.db is local development data. Do not include it in your pull request.

Before committing, check:

git status

If data/products.db appears, leave it unstaged.

I committed the wrong file

If you accidentally staged a file but have not committed yet, unstage it:

git restore --staged data/products.db

If you already committed, ask for help before trying to fix Git history.

I am on the wrong branch

Check your current branch:

git branch

The current branch has a * next to it. To switch branches:

git checkout branch-name

If you have uncommitted work, Git may stop you from switching branches. Ask for help if you are unsure what to do.

Pull request has no linked issue

Pull requests should link to an issue. In the pull request description, include:

Closes #12

Replace 12 with the correct issue number.

My branch is behind master

If your branch is behind master, first make sure your work is committed. Then ask for help if you are not comfortable updating your branch yet.

Keeping branches up to date is normal, but it is better to ask than accidentally lose work. See the Git commands page for how to update your branch.

I am stuck

Being stuck is part of learning. When asking for help, include:

• what you were trying to do
• what command you ran
• what happened
• what you expected to happen
• any error message you saw

Clear questions are easier to answer.

Can I work without an issue?

Usually, no. Create or find a GitHub issue before starting work. This keeps the project organized and gives others a chance to comment.

Small typo fixes may seem simple, but creating an issue is still preferred for transparency.

Can I create my own issue?

Yes. If you find a bug, have an idea, or notice documentation that could be improved, create an issue. Use the correct template, describe the problem clearly, add the right label, and link the issue to the project board.

Can I work on more than one issue?

It is better to finish one issue before starting another. Small focused work is easier to review and merge. If you want to work on multiple things, use separate branches and separate pull requests.

Should I include data/products.db in my pull request?

No. data/products.db is local development data and should not be part of normal pull requests. If it appears in git status, do not stage or commit it.

Do I need automated tests?

For now, manual testing is acceptable for many small changes. As the project grows, automated tests should be added for important behavior. If you add or change behavior that is easy to test, adding a simple test is encouraged.

Where should project discussions happen?

• GitHub Issues for bugs, tasks, and feature ideas
• Pull request comments for code review
• Discord for quick discussion and coordination

If a decision affects the project long term, it should be documented in GitHub or the wiki.