Troubleshoot image-copy and file-validation issues

Guides you through troubleshooting image-copy and file-validation issues by confirming connectivity and storage, resolving image transfer problems, verifying filenames and SHA-512 hashes, addressing image compatibility, and safely managing free space for upgrade, ISSU, xFSU, SMU, or recovery operations.

Procedure

Confirm connectivity and storage.
1. Verify writable filesystems and available storage.
  Example:
```
switch# show file systems | include flash|usb
*  11250098176  4123000832  disk  rw  bootflash: flash:
      8000000000  2950000000  disk  rw  flash-2:
               -           -  disk  rw  usbflash0:
```
  Confirm the exact writable filesystem, available space on every required member, and whether USB is detected.
2. Test transfer-server reachability.
  Example:
```
switch# ping <SERVER_IP> 
Type escape sequence to abort.
Sending 5, 100-byte ICMP Echos to <SERVER_IP>, timeout is 2 seconds:
!!!!!
Success rate is 100 percent (5/5)
```
  Specify the IP address of the server.
  
  Reachability succeeds in the default routing table. Use the appropriate VRF-aware ping when management traffic uses another VRF.
3. Verify the route to the transfer server.
  Example:
```
switch# show ip route <SERVER_IP> 
Routing entry for <SERVER_PREFIX>
  Known via <ROUTING_SOURCE>
  * <NEXT_HOP>, via <INTERFACE>
```
  The switch has a route to the transfer server. Confirm that the return path, ACLs, and firewall also permit the chosen protocol.
Troubleshoot TFTP transfer behavior.
1. Verify if the TFTP image copy action was successful.
  Example:
```
switch# copy tftp://192.0.2.10/images/<IMAGE.bin> flash:
Destination filename [<IMAGE.bin>]?
Accessing tftp://192.0.2.10/images/<IMAGE.bin>...
Loading <IMAGE.bin> from 192.0.2.10: !!!!!!!!!!!!!!!!!!
[OK - <BYTES> bytes]
<BYTES> bytes copied in <SECONDS> secs
```
  The OK message confirms transfer completion, not image integrity. Verify the SHA-512 hash next.
2. Investigate a TFTP timeout.
  Example:
```
switch# copy tftp://192.0.2.10/images/<IMAGE.bin> flash:
%Error opening tftp://192.0.2.10/images/<IMAGE.bin> (Timed out)
```
  Check the server IP and path, routing/VRF, source interface, UDP reachability, server service, ACL, and firewall. Do not repeatedly retry without correcting the failed dependency.
Troubleshoot SCP transfer behavior.
1. Verify an interactive SCP image copy.
  Example:
```
switch# copy scp: flash:
Address or name of remote host []? 192.0.2.20
Source username []? upgradeuser
Source filename []? /images/<IMAGE.bin>
Destination filename [<IMAGE.bin>]?
Password:
!!!!!!!!!!!!!!!!!!
<BYTES> bytes copied in <SECONDS> secs
```
  SCP requires reachable SSH service, valid AAA credentials, and permission to read the exact server path.
2. Investigate SCP permission or path failure
  Example:
```
switch# copy scp://upgradeuser@192.0.2.20//images/<IMAGE.bin> flash:
%Error opening scp://... (Permission denied)
```
  The log indicates that the network reachability exists, but authentication, authorization, file permission, or path validation failed. Correct the server-side account or path rather than changing the switch image.
Troubleshoot USB transfer behavior.
1. Verify USB media detection.
  Example:
```
switch# show file systems | include usb
               -           -  disk  rw  usbflash0:
```
  usbflash0: confirms that supported media is detected.
  
  For ROMMON recovery, Cisco Catalyst 9000 recovery guidance specifies supported FAT32-formatted USB media.
  
  Note
  
  If usbflash0: is absent, reset the media, confirm its filesystem and platform support, and use the exact platform recovery guide. Do not format the switch flash to resolve a USB detection issue.
2. Verify that the image exists on USB.
  Example:
```
switch# dir usbflash0:<IMAGE.bin>
Directory of usbflash0:/

<FILE-ID>  -rw-  <BYTES>  <DATE>  <IMAGE.bin>
```
3. Copy the image from USB to flash.
  Example:
```
switch# copy usbflash0:<IMAGE.bin> flash:
Destination filename [<IMAGE.bin>]?
Copy in progress...!!!!!!!!!!!!!!!!!!
[OK - <BYTES> bytes]
```
Verify the downloaded filename and hash.
1. Verify that the image exists in flash.
  Example:
```
switch# dir flash:<IMAGE.bin>
Directory of flash:/

<FILE-ID>  -rw-  <BYTES>  <DATE>  <IMAGE.bin>
```
2. Verify the SHA-512 hash.
  Example:
```
switch# verify /sha512 flash:<IMAGE.bin>
................................................................
Done!
verify /sha512 (flash:<IMAGE.bin>) = <128-CHAR-SHA512-VALUE>
```
  Compare the entire value with the hash for the exact filename on the official Cisco Software Download website. Similar filenames are not interchangeable.
3. Identify a hash mismatch.
  Example:
```
switch# verify /sha512 flash:<IMAGE.bin>
verify /sha512 (flash:<IMAGE.bin>) = <DEVICE-SHA512>
```
  You must not install the image if DEVICE-SHA512 differs from the Cisco published value, or if the file is wrong, incomplete, corrupted, or altered.
Guidance

Prefer SHA-512 when Cisco Software Download lists it.

Hash mismatch example:

Remove only the confirmed bad staged image, copy it again from a trusted source, and repeat the verification. Do not delete packages.conf, active .pkg files, crash evidence, or rollback files.
Resolve image or package incompatibility.
1. Identify an unsupported image during install.
  Example:
```
switch# install add file flash:<IMAGE.bin> activate commit
FAILED: Image is not supported on this platform
```
  This error occurs when the filename, platform family, product ID, release path, or cryptographic variant does not match the switch variant.
  
  Do not rename the file or try to bypass the check.
2. Verify the exact product ID.
  Example:
```
switch# show inventory
NAME: "Switch 1", DESCR: "<PLATFORM_DESCRIPTION>"
PID: <EXACT_PRODUCT_ID> , VID: <VERSION> , SN: <SERIAL>
```
3. Verify the current release and image source
  Example:
```
switch# show version | include IOS XE Software|System image file
Cisco IOS XE Software, Version <CURRENT_RELEASE>
System image file is "flash:packages.conf"
```
4. Download the correct software image from the Cisco Software Download website by selecting the exact product ID, current release, target release, and required image family.
Confirm whether the deployment requires the standard, NPE, or other platform-specific image variant and whether an intermediate release or ROMMON update is required. Images of Cisco Catalyst 9000 and C9000 Smart switch families are not interchangeable.
Safely handle insufficient space.
1. Check free space on flash and retained files.
  Example:
```
switch# dir flash:
Directory of flash:/

<FILE-ID>  -rw-  <BYTES>  <DATE>  packages.conf
<FILE-ID>  -rw-  <BYTES>  <DATE>  <IMAGE.bin>
...
11250098176 bytes total (4123000832 bytes free)
```
  Compare free space with the exact target release notes. Check the data for every stack-member or supervisor filesystem involved in the operation.
2. Remove inactive packages after reviewing the deletion list.
  Example:
```
switch# install remove inactive
install_remove: Removing IMG
Cleaning up unnecessary package files
Preparing packages list to delete ... done.

The following files will be deleted:
[1]:
/flash/<OLD-INACTIVE-FILE-1>
/flash/<OLD-INACTIVE-FILE-2>

Do you want to remove the above files? [y/n] y
SUCCESS: Files deleted.
Post_Remove_Cleanup: Passed
```
  Read the complete deletion list before answering Yes (y). This command can also select a newly copied .bin file.
Use the supported cleanup workflow before copying the target image whenever possible.

Do not run cleanup while an uncommitted upgrade or a possible rollback is still being evaluated. Archive the required crash files externally before removing them.

Procedure

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example:

Example: