Skip to main content
dev-tools

Hex, Octal and Binary: Reading Numbers in Production Bugs

Two incidents, one root cause. In the first, a brand color arrived as #fff, someone stripped the hash, and a CSS variable held fff — not a color, not a number, just a dead declaration, so the heading rendered invisible on white. In the second, a deploy script ran chmod 644 on an uploads directory instead of 755. Nginx answered 403 for an hour, and the logs said nothing about permissions. Both bugs had the same shape: the number was fine, the base was wrong.

Three bases, three different jobs

Decimal is for counting things people own. Hex is for bytes: two hex digits describe exactly one byte, which is why colors, hashes, MAC addresses and memory dumps all use it. Octal is for Unix file modes and almost nothing else. Binary is for flags, where you need to see individual bits rather than their sum.

The same string means four different values depending on its base: 10 is ten, two, sixteen and eight. That is the whole bug class in one line. A number never travels alone — the base travels with it, and any place that drops the base (a spreadsheet cell, a URL query string, a JSON field, a chat message) becomes a place where the value can quietly change.

Octal survives in chmod and nowhere else

Every file mode is three octal digits: owner, group, others. Each digit is a sum of 4 (read), 2 (write) and 1 (execute). So 755 is rwxr-xr-x, 644 is rw-r--r--, and 600 is a private key nobody else may touch. In decimal those same digits would be meaningless — 755 decimal is 0o1363, a mode nobody ever intends.

The failures repeat in the same order:

  • 644 on a directory. Without the execute bit you cannot traverse it, so the web server returns 403 even though the files inside are readable.
  • 777 to "fix" a permission problem. It works, and it also makes every uploaded script executable by anyone.
  • 666 on .env or a key file. Read access is exactly what you were trying to prevent.
  • 755 on files. Harmless until someone drops a shell script in that folder.

Octal also leaks into code as the leading-zero literal. In PHP, 0755 is octal 493 and correct; 755 is decimal 755 and wrong. In Python 3, 0755 is a syntax error and must be written 0o755. In strict-mode JavaScript it is also a syntax error. And JSON has no octal at all: {"mode": 0755} is invalid JSON, which is why permission settings shipped through a JSON config tend to arrive as the string "755" and then get parsed by whatever the receiving language decides.

The leading-zero trap in parsers

parseInt("08") returned 0 in old engines because the string started with a zero and was read as octal, where 8 does not exist. Modern engines return 8, which means the same code now behaves differently across runtimes. The fix has been the same for fifteen years: always pass a radix.

parseInt(value, 10) removes the ambiguity. Watch the neighbours too: Number("0x1f") is 31 while Number("1f") is NaN; Number("") is 0, not an error; and a value like "1e3" is a thousand, not a failed conversion. When a config value comes from an environment variable, assume nothing about its base and validate the shape before you convert it.

Hex is a byte, not a color

CSS shorthand is the most misread notation on the web. #fff is not three bytes of zero to fifteen — each digit is duplicated, so it means #ffffff. #abc is #aabbcc, not #0a0b0c. Eight-digit hex adds alpha last: #ff000080 is half-transparent red. Getting the expansion wrong shifts every channel, which is why a "slightly off" brand color usually turns out to be a shorthand that was expanded by hand.

The same bytes appear as decimal RGB triples in design tools and as hex in code. rgb(255, 128, 0) and #ff8000 are one value; converting between them by eye is where the off-by-one enters. A converter does it without arithmetic — see the color format converter for hex, RGB and HSL in one place.

Hashes obey the same rule at a larger scale. Eight hex characters are 32 bits, sixteen are 64 bits, and forty are 160. If a stored hash shows seven characters where you expected eight, a leading zero was lost somewhere in a decimal round-trip. Prefixes are part of the value as well: 0x means hex, 0o or a leading zero means octal, 0b means binary. Stripping a prefix during serialization is how a value changes base without anyone editing it.

Binary is for flags, and flags are where shifts bite

Permission masks, feature flags and protocol headers are integers you read bit by bit. Bit 0 is worth 1, bit 1 is worth 2, bit 3 is worth 8, bit 7 is worth 128. A mask of 0b110 means "the 4 and 2 flags are on". The classic mistake is confusing a bit index with a bit value: to test bit 3 you mask with 1 << 3 (8), not with 3.

In shell, $(( 1 << 3 )) is 8 and 0x7f is 127 — the DEL character, which is why striping the high bit from text is still a live trick in log cleaners. When you suspect a mask, print the value in all three bases side by side rather than reasoning about it in your head.

Convert before you theorize

When a number looks wrong, do not start guessing at the business logic. Read the literal exactly as written, including its prefix, and convert it to decimal and hex at the same time. Nine out of ten "impossible" values are one of these: an octal mode read as decimal, a hex color read as three separate values, a bit index used as a mask, or a truncated hash missing its leading zero.

Two tools cover the whole loop. The number base converter takes a value in any base and returns decimal, hex, octal and binary together, which is what you want when the answer is not obvious. The binary converter is faster for single values and for checking whether a mask really has the bit you think it has.

A check-list before you paste a number

  • Does the literal still have its prefix? 0x, 0o, 0b or a leading zero all carry meaning.
  • Is this a file mode, a color, a mask or a hash? Each one has a correct base and a wrong one that still parses.
  • Did it pass through JSON or an environment variable, where leading zeros and prefixes are often lost?
  • If it is a permission, is the target a file or a directory? Directories need the execute bit.
  • If it is a flag, are you testing a bit index or a bit value?
  • If it is a hash, is the length exactly what the algorithm produces?

None of this is hard arithmetic. It is discipline about notation, and notation is where production breaks quietly, because a wrong base still produces a valid number — just never the one you meant.