Troubleshooting Reputation Monitor

Application version: 1.0.0Documentation version: 1.0.4Last technical review: 2026-10-17View Source Code on GitHub →

Written by Elena David, SEO, ORM, and AI Visibility Consultant.

Begin from the project root with the virtual environment active.

Initial checks

python --version
reputation-monitor --help
python -m pip show reputation-monitor

The Python version must be 3.11 or newer, and the help command must list the four documented options.

Problems and corrective actions

Problem	Likely cause	Verification	Next action
`reputation-monitor: command not found`	Environment inactive or package not installed.	Check the Python path and `pip show` output.	Activate `.venv`; run `python -m pip install ".[dev]"`.
`streamlit: command not found`	Environment inactive or runtime dependencies missing.	Run `python -m pip show streamlit`.	Activate `.venv`; reinstall the project.
Input file not found	Wrong working directory or path.	List both paths supplied to the CLI.	Run from the project root or provide correct absolute paths.
`Missing required columns`	Header missing, misspelled, or wrong case.	Compare row 1 with the seven exact field names.	Correct the export header and rerun.
`File is not valid UTF-8`	Different file encoding.	Inspect the export encoding in its source tool.	Export as UTF-8; do not merely rename the file.
CSV shows rejected reviews	One or more records contain missing, invalid, or duplicated required information.	Compare the dashboard's imported and rejected counts with the source file.	Correct the source records and upload the file again; use application logs when record-level diagnostics are required.
Malformed-row warning	Required value, date, rating, or unique ID invalid.	Inspect the reported CSV row.	Correct the source record or document why it should remain excluded.
Too many new reviews	Stable IDs changed or previous valid rows were skipped.	Compare IDs and previous-snapshot warnings.	Restore stable IDs and correct invalid previous rows.
Too few new reviews	IDs were reused or new rows were malformed.	Compare current warnings and duplicate IDs.	Assign unique stable IDs and correct malformed values.
No alerts	No valid new row meets the threshold.	Compare new-review count, row ratings, and threshold.	Confirm this is expected; do not alter IDs to manufacture alerts.
New-review metrics show `Not calculated`	No previous CSV was uploaded.	Check the dashboard's previous-snapshot field.	Supply a valid previous snapshot if comparison is required.
Website destination is blocked	URL is invalid or resolves to local, private, reserved, or link-local space.	Confirm the scheme, hostname, DNS result, and every redirect.	Use an authorized public HTTP(S) source; do not bypass the safeguard.
Website import is disallowed	`robots.txt` prohibits the requested page or cannot be verified.	Inspect the site's published robots rules.	Use a permitted export or CSV; do not retry to evade the rule.
No reviews found on website	Accessible HTML contains no supported review records.	Inspect returned page source for JSON-LD, Microdata, configured selectors, or `article.review`.	Use a page containing server-rendered review data or an authorized CSV export.
Unsupported review HTML	Review-like content does not match a supported extractor.	Compare the static HTML with the data reference.	Configure stable CSS selectors or use an authorized export.
Detected records cannot be analyzed	Required rating, date, practice name, or review text is missing or invalid.	Read preview validation findings.	Correct the source or choose a complete export; do not invent values.
Website request timed out or returned HTTP error	Network or origin failure.	Retry the URL in a browser and note the HTTP status.	Wait for the authorized source to recover; avoid repeated automated requests.
Output files missing	Run stopped before or during writing.	Read the `ERROR:` line and process status.	Correct input or output path and rerun.
Output location error	Directory not writable or path points through a file.	Try creating a normal file in the parent directory.	Choose a writable `--output-dir`.
`No module named pytest`	Development extra absent.	Run `python -m pip show pytest`.	Install with `python -m pip install ".[dev]"`.
Test counts differ	Tests changed or collection failed.	Run `python -m pytest -v`.	Resolve collection errors and inspect the current test files.

Diagnose unexpected counts

Use this order:

Count raw data rows in each CSV.
Read every validation warning.
Use the terminal's valid counts rather than raw row counts.
Compare valid current IDs against valid previous IDs.
Apply the chosen numerical threshold only to the resulting new IDs.

For the unchanged sample, the expected sequence is:

15 previous valid
20 current data rows
2 current malformed rows
18 current valid
3 new valid IDs
2 new IDs rated at or below 2

Reports exist but appear stale

The application overwrites fixed filenames in the selected directory. Confirm the generation timestamp in the HTML report and the paths printed by the latest run. A browser can also display a previously opened local file until it is refreshed.

Collect reproducible diagnostic information

Record:

Python version;
exact command, excluding sensitive paths when shared externally;
process status;
standard output and standard error;
input header and synthetic reproduction rows;
report path;
pytest result.

Do not include patient data or medical information in a reproduction case. For control-flow details, see Error handling and validation.

Continue with CSV after a blocked import

Access restrictions can prevent import even when a page opens normally in a browser. The website may prohibit automated retrieval, require authentication, enforce anti-bot controls, or rate-limit requests. Reputation Monitor preserves these restrictions and does not attempt a bypass.

The dashboard displays:

> Reviews couldn't be imported from this website. > > This website restricts automated access. You can still analyze your reviews by uploading a CSV file.

Select Switch to CSV Upload below the message.
Confirm that the selected maximum alert rating is unchanged.
Upload an authorized current CSV.
Upload a previous CSV when new-review detection is required.
Confirm how many reviews are ready for analysis and how many were rejected before continuing.

Do not treat an unsupported-format message as an access restriction. Unsupported format means the page was retrieved but its static review markup did not match JSON-LD, Microdata, configured selectors, or article.review. In either case, CSV upload remains available.

Interpret CSV import messages

For a complete current import, the dashboard displays Current reviews imported successfully — X reviews ready for analysis. For a complete previous import, it displays Previous reviews imported successfully — X reviews available for comparison. The actual imported count replaces X.

For a partial import, the message reports both the usable review count and the rejected count. It explains that rejection results from missing, invalid, or duplicated required information without exposing record contents or technical validation details. Those details remain in application logs. When the usable count is zero, correct the file before analysis or comparison.