What does Windows error code 1142 (ERROR_TOO_MANY_LINKS) mean?

 
Previous Next
ERROR_SET_POWER_STATE_FAILED ERROR_OLD_WIN_VERSION

ERROR_TOO_MANY_LINKS

An attempt was made to create more links on a file than the file system supports.

ERROR_TOO_MANY_LINKS is Win32 error 1142 (0x476). It is returned when creating another hard link would exceed the link-count limit for the target file or filesystem. A hard link is another directory entry for the same file data on the same volume; it is not a shortcut, symbolic link, or junction.

Where the limit is reached

  • deduplication, package, backup, or deployment software creates many names for one file
  • a restore process reconstructs a large hard-link set from another filesystem
  • a loop or retry bug repeatedly creates new links instead of detecting existing ones
  • test software deliberately approaches the filesystem maximum
  • metadata corruption or an inconsistent catalog causes the application to overestimate missing links

Microsoft documents a maximum of 1023 hard links per file for CreateHardLink on NTFS. Other filesystems or layers can impose different limits, so log the actual volume filesystem and API instead of hard-coding one assumption for every target.

Evidence to collect

  • source file identity, volume GUID, filesystem type, and existing link count
  • new link path, target path, and whether the directory entry already exists
  • operation ID from the restore or deployment job
  • list or sample of existing hard-link names
  • whether the source data came from a filesystem with a higher supported link count

Use file identity rather than pathname alone. Several paths can reference the same file record, and deleting one name does not remove the underlying file while other hard links remain.

Handling the failure

Do not automatically delete an arbitrary existing link to make room. Each name may be part of a package, snapshot, or backup contract. Decide whether the new name is required, whether an old name is obsolete, or whether the object should be copied as an independent file.

A restore tool should preserve semantics where possible and clearly report degradation when it must replace a hard link with a separate copy. That fallback changes space usage and future update behavior, so it should not be silent.

Developer recommendations

  • detect duplicate destination requests before calling CreateHardLink
  • track file IDs and link groups during backup or restore
  • make operations idempotent so job retries do not create additional names
  • validate cross-filesystem migrations against the destination link-count limit
  • log 1142 separately from path-exists and cross-volume errors

Hard links can only reference files on the same volume. A cross-volume design must copy data or use a different indirection mechanism; changing paths does not bypass that rule.

Related errors

ERROR_ALREADY_EXISTS means the requested directory entry already exists. ERROR_NOT_SAME_DEVICE can appear for operations that cross volumes. Error 1142 specifically says the existing file has reached the supported number of hard-link names.

Example

A package cache links one common payload into thousands of version directories. After the 1023rd NTFS link, the next CreateHardLink call returns 1142. The durable design is to shard payload files or use a catalog plus fewer links, not to delete names belonging to installed versions.

References

Looking for a different code? Search another status or error code.