ABSTRACT We use the IllustrisTNG cosmological, hydrodynamical simulations to test fundamental assumptions of the mass-based halo occupation distribution (HOD) approach to modelling the galaxy–halo connection. By comparing the clustering of galaxies measured in the 300 Mpc TNG box (TNG300) with that predicted by the standard (basic) HOD model, we find that, on average, the ‘basic’ HOD model underpredicts the real-space correlation function in the TNG300 box by ∼15 per cent on scales of $1 \,\,\lt\,\, r \,\,\lt\,\, 20 \ {\rm Mpc}\, h^{-1}$, which is well beyond the target precision demanded of next-generation galaxy redshift surveys. We perform several tests to establish the robustness of our findings to systematic effects, including the effect of finite box size and the choice of halo finder. In our exploration of ‘secondary’ parameters with which to augment the ‘basic’ HOD, we find that the local environment of the halo, the velocity dispersion anisotropy, β, and the product of the half-mass radius and the velocity dispersion, σ2Rhalfmass, are the three most effective measures of assembly bias that help reconcile the ‘basic’ HOD-predicted clustering with that in TNG300. In addition, we test other halo properties such as halo spin, formation epoch, and halo concentration. We also find that at fixed halo mass, galaxies in one type of environment cluster differently from galaxies in another. We demonstrate that a more complete model of the galaxy–halo connection can be constructed if we combine both mass and local environment information about the halo.