# Troubleshooting

## Build failures

Check the following if the project fails to build or generate a bitstream:

1. **Are you using the correct version of Vivado for this version of the repository?**   
   Check the version specified in the Requirements section of the README.md file. Note that this project is regularly updated
   and you may have to refer to an earlier commit of this repo if you are using an older version of Vivado.

2. **Did you correctly follow the build instructions?**   
   Please check the build instructions carefully as you may have missed a step.

3. **Did you copy/clone the repo into a short directory structure?**   
   Windows doesn't cope well with long directory structures, so copy/clone the repo into a short directory structure such as
   `C:\projects\`. When working in long directory structures, you can get errors relating to missing files, particularly files 
   that are normally generated by Vivado (FIFOs, etc).

## PetaLinux issues

### Build fails with `bitbake petalinux-image-minimal failed` and sstate fetch errors

If `./build.sh petalinux --target <board>` ends with errors like:

```
ERROR: <package>-<ver>-r0 do_..._setscene: Fetcher failure: Unable to find file file://.../sstate:...
[ERROR] Command bitbake petalinux-image-minimal failed
```

the build is not actually broken. These `_setscene` errors come from bitbake
trying to pull prebuilt artifacts from the public Xilinx sstate-cache mirror,
which intermittently returns 404 for individual packages. Bitbake falls back
to building them locally and succeeds, but exits non-zero because of the
failed fetches, so the build runner stops before `petalinux-package` runs and no
`BOOT.BIN` is produced.

**Fix: re-run the same command.** The second attempt finds the missing
packages in the local sstate cache populated by the first run and completes
cleanly. This is a mirror issue, not a problem with the reference design.


### Ports not working

Check the following if you are unable to get ports working in PetaLinux.

1. **Check the interface-to-port assignment for your design**   
   The assignment of interfaces (`end0`, `end1`, `end2`, etc. — PetaLinux 2025.2 uses the
   `endN` predictable naming) to physical Ethernet FMC Max ports is specific to the target
   design. See the [Port configurations](petalinux.md#port-configurations) section for the
   per-target mapping. Note that on ZynqMP designs the development board's onboard Ethernet
   port also appears (typically as `end3`), and on Versal it appears at `end4`/`end5`.

2. **Each port must be assigned to a different subnet**   
   If you assign one interface to IP address 192.168.1.10, then you must use a different
   subnet for the IP addresses of the other interfaces. Multiple ports that are managed
   under Linux must be assigned to different subnets, or they will not work.
   For example: `end0=192.168.1.10`, `end1=192.168.2.10`, `end2=192.168.3.10`,
   `end4=192.168.4.10`.

### Dropped pings/packets

No dropped packets are to be expected with our example designs. If you are experiencing dropped packets of any kind, please ensure that
you have no timing errors or critical warnings in the Vivado design.

We ensure that there are no timing errors or issues on all of our designs before making a release, so typically this problem occurs on
custom designs where the timing issues have not yet been optimized. Please [contact us](https://opsero.com/contact-us/) for support 
if you are experiencing dropped packets.