Debugging & Troubleshooting

NoteWhere are you stuck?

Jump to the right section:

WarningSAVE YOUR FILES

95% of your problems are caused by not saving files ! Always check that your files are saved before compiling or running or pushing/pulling.

  • Unsaved changes are not compiled, so you may be running an old version of your code without realizing it.
  • Unsaved changes are not pushed, so your teammates don’t see them until you save and push.
  • vscode don’t reflect modified files from git if you have unsaved changes, which can lead to confusion when you pull changes from teammates and don’t see them in the editor. Always save your files to ensure you are working with the latest version of the code.

1. Can’t get started

Problems before you write any code: environment, tools, libraries.

Path and encoding — project won’t compile

No accents or special characters anywhere in your path.

✗ C:\Users\elodie.bouzekri\Documents\Ma bibliothèque\Génie Info\
✓ C:\projetInfo\pgi-2026-your-team\

Clone your project into a short, accent-free path like C:\projetInfo\pgi-2026-your-team.

MinGW not found or too old

Check that MinGW is installed at C:\MinGW\bin:

  • If missing, download: mingw-19.0.exe
  • If present but not working, add C:\MinGW\bin to your Path environment variable, then restart VS Code

Git not recognized in VS Code

If Git: Clone does nothing in the command palette:

  1. Check that Git is installed at C:\MinGW\git\bin
    • If missing, download: Git-2.36.1-64-bit.exe
    • If present, add C:\MinGW\git\bin to your Path environment variable
  2. Check that your folder is marked as trusted in VS Code:
    • Click the gear icon (bottom-left) → Manage Workspace Trust → Trust

Git authentication fails

If Git asks for credentials repeatedly or is not authorized with GitHub:

git config --global credential.useHttpPath true

This forces Git to open a browser to set up authentication.

CMake version too old

If CMake reports a version mismatch, lower the minimum required version in CMakeLists.txt:

# Change:
cmake_minimum_required(VERSION 3.20)
# To:
cmake_minimum_required(VERSION 3.15)

Libraries not found by CMake

CMake Error: Could not find a package configuration file provided by "estia-image"

Check that both library folders exist at the root of your project (next to src/, CMakeLists.txt):

pgi-2026-your-team/
├── estia-image/
│   ├── include/
│   └── lib/
├── getopt/
│   ├── include/
│   └── lib/
├── src/
└── CMakeLists.txt

If you extracted the zip and the folder is wrapped in an outer folder, move only the inner folder:

✗ Wrong:
estia-image-v2.0.1-win10-mingw32/
    estia-image/         ← this is what you need
        include/
        lib/

✓ Correct — estia-image/ sits directly in the project root

See Setup — Phase 3 for full instructions.

How do I choose the right library package?

The deciding factor is the CPU architecture prefix, not the mingw suffix:

gcc -dumpmachine
Output starts with Download
x86_64 *-win10-mingw64.zip
i686 *-win10-mingw32.zip

x86_64-w64-mingw32 → the x86_64 prefix means 64-bit → download mingw64.

Packages: v2.0.1 release.

2. Code won’t compile

Problems during cmake -B build or cmake --build build.

First step — always run:

bash validconfig.sh

This checks common configuration mistakes and gives actionable messages before you dig into the raw error log.

Reading compiler errors

The compiler reports the first error. Fix it, rebuild, then move to the next. Do not try to fix multiple errors at once.

Error message Likely cause
implicit declaration of function 'foo' foo declared in .h but the .h is not #included in your .c
undeclared identifier 'foo' Missing #include or typo in the name
error: expected ';' Missing semicolon — usually one line before the reported line
undefined reference to 'foo' Function declared but not implemented, or not listed in CMakeLists.txt
too few/many arguments Function signature in .h does not match the call site

Feature compiles but freud.exe -c my_feature does nothing

Check main.c — every feature needs a dispatch branch:

if (strcmp(conf.command, "my_feature") == 0) {
    my_feature(conf.filenames[0]);
}

If this block is missing, your function is never called regardless of how correct it is.

Feature is not tested by the CI

Check freud.manifest — the command name must appear on its own line, exactly:

helloworld
dimension
my_feature

No spaces, no quotes, no extra characters. The CI reads this file to discover which features to test. If the entry is missing, the CI skips your feature entirely.

cmake: argument numérique non valide '/Wextra'

CMake may report D8021, argument numérique non valide '/Wextra', or similar /W-prefixed flag errors.

Cause

Your CMake configuration is using MSVC (Microsoft Visual Studio) instead of MinGW/GCC.
The /W flags are MSVC-style; MinGW uses -W flags. The two compilers are incompatible.

Fix / Correction

  1. Delete the ./build/ directory.
rm -rf build
  1. Configure with MinGW/GCC explicitly from the command line (no extension required):
CC=gcc cmake -B build -G "Unix Makefiles"

If needed, also force the compiler path:

cmake -B build -G "Unix Makefiles" -DCMAKE_C_COMPILER=gcc

On some setups, -G "Unix Makefiles" is required, otherwise CMake picks a Windows/MSVC generator again.

Alternative with the VS Code CMake extension: Open the command palette (Ctrl+Shift+P) and run CMake: Select a Kit, then choose a GCC/MinGW kit.

  1. Build:
cmake --build build

DependInfo.cmake: No such file or directory

Cause

Same root cause as above: wrong generator/compiler was selected, and ./build/ is now inconsistent.

Fix / Correction

  1. Delete ./build/:
rm -rf build
  1. Reconfigure with MinGW/GCC from command line:
CC=gcc cmake -B build -G "Unix Makefiles"

If needed:

cmake -B build -G "Unix Makefiles" -DCMAKE_C_COMPILER=gcc

If you use the VS Code extensions (CMake and CMake Tools), you can also select a GCC/MinGW kit via CMake: Select a Kit.

  1. Build:
cmake --build build

3. Code runs but behaves wrong

Code compiles but the the output never changes when I do changes

Problems after a successful build: wrong output, black image, crash.

Output image is black or all zeros

You allocated the output buffer but never wrote to it:

unsigned char *out = malloc(width * height * 3);
// Nothing written → garbage or zeros
write_image_data(output_path, out, width, height);

Make sure you fill every pixel before calling write_image_data.

Output image dimensions are wrong

write_image_data requires the correct width and height for the output buffer. If you change dimensions (crop, rotate, scale), you must pass the new dimensions — not the original ones.

Program crashes — segmentation fault

A segfault means your code accessed memory it doesn’t own. Three most common causes:

1. Off-by-one when iterating

// WRONG — goes one byte past the end
for (int i = 0; i <= width * height * 3; i++) { ... }

// CORRECT
for (int i = 0; i < width * height * 3; i++) { ... }

2. Array index out of bounds

// Pixel at (x, y): index = (y * width + x) * 3
int index = (y * width + x) * 3;
// Always verify: x < width, y < height, index + 2 < width * height * 3

3. Null pointer — read_image_data failed

unsigned char *data = NULL;
int width, height, channels;
int error = read_image_data(filename, &data, &width, &height, &channels);
if (error) {
    fprintf(stderr, "Error: could not read image\n");
    return;
}
// Only use data here, after the check

Always check the return value of read_image_data before using data.

Output format doesn’t match — CI test fails

The CI compares your output character by character against the reference. Check:

  • Exact spacing: dimension: 1488, 1488 not dimension: 1488,1488
  • Exact capitalization: max_pixel not Max_Pixel
  • No trailing spaces or extra newlines

Re-read the feature’s issue file for the exact expected format.

4. Git & GitHub

Push rejected

error: failed to push some refs to 'origin/main'

Your teammate pushed after your last git pull. Fix:

git pull --rebase
# resolve any conflicts, then:
git push

Merge conflict

Git shows <<<<<< / ======= / >>>>>>> markers. Two people edited the same lines.

  1. Open the file in VS Code — conflicts are highlighted.
  2. Choose which version to keep (or combine both).
  3. Remove all conflict markers.
  4. git add the resolved file, then git commit.
Tip

Conflicts on features.c and features.h are common when two people work in parallel. Prevent them: one person per file at a time, always git pull before starting a session.

Accidentally committed to the wrong branch

git reset --soft HEAD~1  # undo last commit but keep changes
git checkout right_branch       # switch to the right branch (change the name to the branch you want)
git add .                # stage changes again
git commit -m "Your commit message"

I don’t see the modification of my teammate

Issues not appearing in my repository

  1. Go to your repository on GitHub → Actions tab.
  2. Run Import issues from Template manually → Run workflow.
  3. Wait for the green checkmark.
  4. Refresh the Issues tab.

CI fails but code works locally

  1. Open the Actions tab on GitHub and read the workflow output.
  2. Confirm your latest commit is on main (not a feature branch).
  3. Check your output format matches exactly — spacing, capitalization, line endings all matter.

CI passes but grade doesn’t update

Evaluation runs on a daily schedule triggered by the teacher — not on every push. Wait for the next run. You can check the last run time in the Actions tab.

5. Team coordination

What does the team leader need to do?

Exactly one thing no one else should do: run workflow activation once, after every teammate has successfully run bash validconfig.sh and built helloworld.

bash validconfig.sh --activate-workflows

This renames disabled workflow files and pushes an onboarding commit. Announce to your team — everyone else runs git pull.

My teammate already activated workflows

Run git pull. You do not need to run --activate-workflows yourself.

Who triggers the issue import?

One person only. GitHub → Actions → Import issues from Template → Run workflow. Everyone else waits, then runs git pull once issues appear.

Can we split Milestone 1 issues and work in parallel?

No. Milestone 1 is mob programming — all three of you on the same machine, rotating who types. See First Steps — Milestone 1.

Splitting Milestone 1 means some teammates never learn to open an image, access pixels, or add a feature — which directly hurts them in the individual final exam.

Still stuck?

  1. Reproduce the problem with the smallest possible input — one tiny image, one feature.
  2. Read the full compiler output — the real error is usually near the top of the first error block.
  3. Ask a teammate or TA: describe what you did, what you expected, and what actually happened.
  4. If you suspect a bug in the reference implementation or test, open a GitHub Issue in your repository — if confirmed, your contribution is noted positively.